Issue Driven Workflow

ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
A1,Backend token validation,"Handle invalid/expired tokens in /auth/login","Returns 401 with structured error code","pytest tests/test_auth.py -k test_invalid_token",none,TODO,TODO,TODO,"src/auth/login.ts | src/auth/token.ts",none,"Phase 1"
A2,SSO provider integration,"Integrate SSO provider OAuth flow","User redirected to SSO and returned with valid session","pytest tests/test_auth.py -k test_sso_flow",none,TODO,TODO,TODO,"src/auth/sso.ts | src/auth/session.ts",A1,"Phase 1"
A3,Dashboard renders after SSO,"Dashboard loads within 3s after SSO login","Page renders with user profile and data","manual: login via SSO then open /dashboard",playwright:browser_navigate,TODO,TODO,TODO,"src/pages/dashboard.tsx",A2,"Phase 2"

#!/usr/bin/env python3
"""Create a repo-local plan markdown file under ./plan."""

from __future__ import annotations

import argparse
import sys
from pathlib import Path

from plan_utils import (
    build_plan_filename,
    format_yaml_value,
    get_assets_dir,
    get_plans_dir,
    now_iso,
    now_timestamp,
    replace_placeholders,
    slugify,
    validate_slug,
)

ALLOWED_COMPLEXITY = {"simple", "medium", "complex"}


def read_body(args: argparse.Namespace) -> str | None:
    if args.template:
        template_path = get_assets_dir() / "_template.md"
        return template_path.read_text(encoding="utf-8")
    if args.body_file:
        return Path(args.body_file).read_text(encoding="utf-8")
    if not sys.stdin.isatty():
        return sys.stdin.read()
    return None


def main() -> int:
    parser = argparse.ArgumentParser(description="Create a plan file under ./plan.")
    parser.add_argument("--task", required=True, help="Short task/title for the plan.")
    parser.add_argument(
        "--complexity",
        default="medium",
        choices=sorted(ALLOWED_COMPLEXITY),
        help="Plan complexity: simple|medium|complex.",
    )
    parser.add_argument(
        "--slug",
        help="Optional slug override for the plan filename (lower-case, hyphen-delimited).",
    )
    parser.add_argument(
        "--timestamp",
        help="Override timestamp for the filename (YYYY-MM-DD_HH-mm-ss).",
    )
    parser.add_argument(
        "--created-at",
        dest="created_at",
        help="Override created_at frontmatter (ISO8601).",
    )
    parser.add_argument(
        "--body-file",
        help="Path to markdown body (without frontmatter). If omitted, read from stdin.",
    )
    parser.add_argument(
        "--template",
        action="store_true",
        help="Use the skill's plan template instead of stdin or --body-file.",
    )
    parser.add_argument(
        "--overwrite",
        action="store_true",
        help="Overwrite the plan file if it already exists.",
    )
    args = parser.parse_args()

    task = args.task.strip()
    if not task or "\n" in task:
        raise SystemExit("Task must be a single line.")

    slug = args.slug.strip() if args.slug else slugify(task)
    validate_slug(slug)

    timestamp = args.timestamp.strip() if args.timestamp else now_timestamp()
    filename = build_plan_filename(timestamp, slug)

    created_at = args.created_at.strip() if args.created_at else now_iso()

    body = read_body(args)
    if body is None:
        raise SystemExit("Provide --body-file, stdin, or --template to supply plan content.")

    body = body.strip()
    if not body:
        raise SystemExit("Plan body cannot be empty.")
    if body.lstrip().startswith("---"):
        raise SystemExit("Plan body should not include frontmatter.")

    body = replace_placeholders(body, timestamp, slug)

    plans_dir = get_plans_dir()
    plans_dir.mkdir(parents=True, exist_ok=True)
    plan_path = plans_dir / filename

    if plan_path.exists() and not args.overwrite:
        raise SystemExit(f"Plan already exists: {plan_path}. Use --overwrite to replace.")

    frontmatter = (
        "---\n"
        f"mode: {format_yaml_value('plan')}\n"
        f"task: {format_yaml_value(task)}\n"
        f"created_at: {format_yaml_value(created_at)}\n"
        f"complexity: {format_yaml_value(args.complexity)}\n"
        "---\n\n"
    )

    plan_path.write_text(frontmatter + body + "\n", encoding="utf-8")
    print(str(plan_path))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""List repo-local plan summaries by reading frontmatter only."""

from __future__ import annotations

import argparse
import json

from plan_utils import get_plans_dir, parse_frontmatter


REQUIRED_KEYS = {"task", "created_at", "complexity"}


def main() -> int:
    parser = argparse.ArgumentParser(description="List plan summaries from ./plan.")
    parser.add_argument("--query", help="Case-insensitive substring to filter task/path.")
    parser.add_argument("--json", action="store_true", help="Emit JSON output.")
    args = parser.parse_args()

    plans_dir = get_plans_dir()
    if not plans_dir.exists():
        raise SystemExit(f"Plans directory not found: {plans_dir}")

    query = args.query.lower() if args.query else None
    items = []
    for path in sorted(plans_dir.glob("*.md")):
        try:
            data = parse_frontmatter(path)
        except ValueError:
            continue
        if not REQUIRED_KEYS.issubset(data.keys()):
            continue
        task = data.get("task", "")
        created_at = data.get("created_at", "")
        complexity = data.get("complexity", "")
        if query:
            haystack = f"{task} {path}".lower()
            if query not in haystack:
                continue
        items.append(
            {
                "task": task,
                "created_at": created_at,
                "complexity": complexity,
                "path": str(path),
            }
        )

    if args.json:
        print(json.dumps(items))
    else:
        for item in items:
            print(
                f"{item['task']}\t{item['created_at']}\t{item['complexity']}\t{item['path']}"
            )

    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Shared helpers for repo-local plan scripts."""

from __future__ import annotations

import re
from pathlib import Path
from datetime import datetime

_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
_FILENAME_RE = re.compile(
    r"^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$"
)
_TIMESTAMP_RE = re.compile(r"^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}$")


def get_repo_root(start: Path | None = None) -> Path:
    """Find the repo root by walking up to .git or AGENTS.md."""
    path = (start or Path.cwd()).resolve()
    for candidate in [path, *path.parents]:
        if (candidate / ".git").exists() or (candidate / "AGENTS.md").exists():
            return candidate
    return path


def get_plans_dir() -> Path:
    return get_repo_root() / "plan"


def get_issues_dir() -> Path:
    return get_repo_root() / "issues"


def get_assets_dir() -> Path:
    return Path(__file__).resolve().parents[1] / "assets"


def slugify(text: str) -> str:
    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
    slug = re.sub(r"-{2,}", "-", slug)
    return slug or "plan"


def validate_slug(slug: str) -> None:
    if not slug or not _NAME_RE.match(slug):
        raise ValueError(
            "Invalid slug. Use short, lower-case, hyphen-delimited names "
            "(e.g., update-login-flow)."
        )


def validate_timestamp(timestamp: str) -> None:
    if not _TIMESTAMP_RE.match(timestamp):
        raise ValueError("Timestamp must be in YYYY-MM-DD_HH-mm-ss format.")


def build_plan_filename(timestamp: str, slug: str) -> str:
    validate_timestamp(timestamp)
    validate_slug(slug)
    return f"{timestamp}-{slug}.md"


def format_yaml_value(value: str) -> str:
    if value is None:
        return ""
    needs_quotes = (
        not value
        or value.strip() != value
        or "\n" in value
        or any(ch in value for ch in (":", "#", "{", "}", "[", "]", ","))
    )
    if needs_quotes:
        escaped = value.replace('"', "\\\"")
        return f'"{escaped}"'
    return value


def replace_placeholders(body: str, timestamp: str, slug: str) -> str:
    body = body.replace("issues/<YYYY-MM-DD_HH-mm-ss>-<slug>.csv", f"issues/{timestamp}-{slug}.csv")
    body = body.replace("<YYYY-MM-DD_HH-mm-ss>", timestamp)
    body = body.replace("<slug>", slug)
    return body


def validate_plan_filename(filename: str) -> None:
    if not _FILENAME_RE.match(filename):
        raise ValueError(
            "Invalid plan filename. Expected YYYY-MM-DD_HH-mm-ss-<slug>.md."
        )


def parse_frontmatter(path: Path) -> dict:
    """Parse YAML frontmatter from a markdown file without reading the body."""
    with path.open("r", encoding="utf-8") as handle:
        first = handle.readline()
        if first.strip() != "---":
            raise ValueError("Frontmatter must start with '---'.")

        data: dict[str, str] = {}
        for line in handle:
            stripped = line.strip()
            if stripped == "---":
                return data
            if not stripped or stripped.startswith("#"):
                continue
            if ":" not in line:
                raise ValueError(f"Invalid frontmatter line: {line.rstrip()}")
            key, value = line.split(":", 1)
            key = key.strip()
            value = value.strip()
            if value and len(value) >= 2 and value[0] == value[-1] and value[0] in ("\"", "'"):
                value = value[1:-1]
            data[key] = value

    raise ValueError("Frontmatter must end with '---'.")


def now_timestamp() -> str:
    return datetime.now().astimezone().strftime("%Y-%m-%d_%H-%M-%S")


def now_iso() -> str:
    return datetime.now().astimezone().isoformat(timespec="seconds")

#!/usr/bin/env python3
"""Read plan frontmatter without loading the full markdown body."""

from __future__ import annotations

import argparse
import json
from pathlib import Path

from plan_utils import parse_frontmatter

REQUIRED_KEYS = {"task", "created_at", "complexity", "mode"}


def main() -> int:
    parser = argparse.ArgumentParser(description="Read frontmatter from a plan markdown file.")
    parser.add_argument("plan_path", help="Path to the plan markdown file.")
    parser.add_argument("--json", action="store_true", help="Emit JSON output.")
    args = parser.parse_args()

    path = Path(args.plan_path).expanduser()
    if not path.exists():
        raise SystemExit(f"Plan not found: {path}")

    data = parse_frontmatter(path)
    if not REQUIRED_KEYS.issubset(data.keys()):
        missing = sorted(REQUIRED_KEYS - set(data.keys()))
        raise SystemExit(f"Frontmatter missing required fields: {', '.join(missing)}")

    payload = {
        "mode": data.get("mode"),
        "task": data.get("task"),
        "created_at": data.get("created_at"),
        "complexity": data.get("complexity"),
        "path": str(path),
    }

    if args.json:
        print(json.dumps(payload))
    else:
        for key in ("mode", "task", "created_at", "complexity", "path"):
            print(f"{key}: {payload[key]}")

    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Validate issues CSV schema and required fields."""

from __future__ import annotations

import csv
import sys
from pathlib import Path

REQUIRED_COLUMNS = [
    "ID",
    "Title",
    "Description",
    "Acceptance",
    "Test_Method",
    "Tools",
    "Dev_Status",
    "Review1_Status",
    "Regression_Status",
    "Files",
    "Dependencies",
    "Notes",
]

STATUS_FIELDS = {"Dev_Status", "Review1_Status", "Regression_Status"}
ALLOWED_STATUS = {"TODO", "DOING", "DONE"}


def fail(message: str) -> int:
    print(f"error: {message}", file=sys.stderr)
    return 1


def main() -> int:
    if len(sys.argv) != 2:
        return fail("usage: validate_issues_csv.py <issues.csv>")

    path = Path(sys.argv[1])
    if not path.exists():
        return fail(f"file not found: {path}")

    rows = []
    with path.open(newline="", encoding="utf-8") as handle:
        reader = csv.reader(handle)
        for row in reader:
            if any(cell.strip() for cell in row):
                rows.append(row)

    if not rows:
        return fail("csv is empty")

    header = rows[0]
    if header != REQUIRED_COLUMNS:
        return fail(
            "invalid header. expected: "
            + ",".join(REQUIRED_COLUMNS)
            + " | got: "
            + ",".join(header)
        )

    seen_ids: set[str] = set()
    for idx, row in enumerate(rows[1:], start=2):
        if len(row) != len(REQUIRED_COLUMNS):
            return fail(f"row {idx}: expected {len(REQUIRED_COLUMNS)} columns, got {len(row)}")

        row_data = dict(zip(REQUIRED_COLUMNS, row))
        for col, value in row_data.items():
            if not value.strip():
                return fail(f"row {idx}: '{col}' is empty")
            if col in STATUS_FIELDS and value.strip() not in ALLOWED_STATUS:
                return fail(
                    f"row {idx}: '{col}' must be one of {sorted(ALLOWED_STATUS)}, got '{value}'"
                )

        issue_id = row_data["ID"].strip()
        if issue_id in seen_ids:
            return fail(f"row {idx}: duplicate ID '{issue_id}'")
        seen_ids.add(issue_id)

    return 0


if __name__ == "__main__":
    raise SystemExit(main())