claude-dev-env 1.65.1 → 1.66.0

package/skills/anthropic-plan/SKILL.md

@@ -1,107 +1,68 @@
 ---
 name: anthropic-plan
-description: Structured implementation planning through readonly codebase exploration before any code changes. Produces a plan file for approval. Use when the user says /anthropic-plan, "plan this first", "think before coding", "explore before implementing", "make a plan", or when approaching non-trivial tasks that benefit from upfront exploration and design. Also triggers on "what would the approach be", "scope this out", or "don't code yet, just plan".
+description: Workflow-backed implementation planning that creates a deep repo-local packet under docs/plans/<slug>/ before any code changes. Use for /anthropic-plan, /plan, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial implementation requests that need source-grounded design, TDD steps, and validator approval before build work.
 ---
 
-# Claude Plan
+# Anthropic Plan
 
-Explore the codebase, design an approach, and write a plan file -- all without touching production code.
+Create a source-grounded plan packet through the Claude Code Workflow runtime. The output is a repo-local `docs/plans/<slug>/` folder with context, spec, implementation, validation, and handoff docs. Stop before implementation.
 
-## Why
+## Launch
 
-Jumping straight to code on non-trivial tasks leads to wasted effort when the approach conflicts with existing patterns, misses reusable code, or misunderstands the user's intent. This skill enforces "look before you leap": explore first, design second, write the plan third, get approval last. No code changes until the user says go.
+Call the workflow with the user request and current working directory:
 
-## Constraints
-
-Treat the codebase as readonly throughout this skill. The only file you may create or edit is the plan file.
-
-**Allowed:** Read files, Grep, Glob, launch Explore agents, launch Plan agents, write/edit the plan file, AskUserQuestion for clarification.
-
-**Not allowed:** Edit source files, Write new source files, run tests, install packages, run non-readonly Bash commands, or make any system changes.
-
-This discipline exists because the user invoked this skill specifically to understand the approach before committing to it. Violating readonly would undermine the whole point.
-
-## Plan File
-
-Write to `~/.claude/plans/<slug>.md`.
-
-Generate the slug from the task -- descriptive, kebab-case, 2-4 words. Examples: `add-user-auth.md`, `fix-payment-retry.md`, `refactor-config-loading.md`. Avoid the random-word convention used by built-in plan mode.
-
-**Announce at start:** "Planning: `<slug>` -- exploring before writing code."
-
-## Workflow
-
-### Phase 1: Explore
-
-Understand the problem space before proposing solutions. Launch Explore agents in parallel -- up to 3, but use the minimum needed. Quality over quantity.
-
-What to look for:
-- Files and modules the task will touch
-- Existing patterns for similar functionality
-- Utilities, helpers, constants, and shared code to reuse
-- Test patterns already in place
-
-Skip this phase only if the task is trivial and full context already exists in the conversation.
-
-### Phase 2: Design
-
-Launch Plan agent(s) to design the implementation -- up to 3 for complex or multi-area tasks, skip entirely for trivial tasks. Feed them comprehensive context from Phase 1; they cannot explore on their own, so everything they need must come from you.
-
-### Phase 3: Review
-
-Before committing to the plan:
-- Read the critical files yourself to verify the agents got it right
-- Check alignment with what the user actually asked for
-- If requirements are ambiguous, use AskUserQuestion now -- not after writing the plan
-
-### Phase 4: Write the Plan
+```js
+Workflow({
+  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
+  input: {
+    task: "$ARGUMENTS",
+    cwd: "<current working directory>"
+  }
+})
+```
 
-Write incrementally as you learn things in Phases 1-3, then refine here. The plan file has these sections:
+If the Workflow tool is unavailable, say `anthropic-plan requires the Workflow tool; aborting` and stop.
 
-```markdown
-## Context
-Why this change is needed, what problem it solves, what the outcome looks like.
+## Workflow Contract
 
-## Approach
-The recommended implementation. One approach, not a menu of alternatives.
-Concise but detailed enough to execute without re-exploring.
+The workflow handles the full planning loop:
 
-## Files
-Critical file paths that will be created or modified.
+1. Resolve repo root and packet path.
+2. Read project instructions, rules, relevant skills, manifests, docs, tests, hooks, agents, commands, configs, and workflows.
+3. Build a source inventory and extract source facts into `context/source-map.md`.
+4. Write the packet under `docs/plans/<slug>/`.
+5. Run `scripts/validate_packet.py`.
+6. Spawn `plan-packet-validator` in fresh context.
+7. Repair packet findings up to the workflow cap.
+8. Return packet path, validation state, and findings.
+9. Stop before implementation.
 
-## Reuse
-Existing functions, utilities, constants, or patterns to leverage.
-Include file:line references so the implementer can find them instantly.
+## Packet Shape
 
-## Steps
-Ordered implementation steps. Each step is a discrete, testable unit of work.
+Required root: `docs/plans/<slug>/`
 
-## Verification
-How to confirm end-to-end that the implementation works.
-Specific commands, test files, or manual verification steps.
+Required top-level files and folders:
 
-## Bash Permissions
-Semantic descriptions of bash actions the implementation will need:
-- "run tests"
-- "install dependencies"
-- "start dev server"
-These are action descriptions, not specific commands.
-```
+- `README.md`
+- `packet.json`
+- `context/`
+- `spec/`
+- `implementation/`
+- `validation/`
+- `handoff/`
 
-### Phase 5: Present for Approval
+The packet depth rule is strict: `README.md` is a thin hub, first-level folders group purpose, and second-level files carry detail. Add `context/subsystems/<name>.md` only when the planner finds more than twelve source files or more than three subsystems.
 
-Use AskUserQuestion to present the completed plan. Do not ask about approval in regular text -- always use AskUserQuestion so the user gets a clear, structured decision point.
+## Validation
 
-Options:
-- **Approve** -- proceed with implementation
-- **Revise** -- user has feedback to incorporate
-- **Cancel** -- abandon the plan
+The deterministic validator checks required files, placeholders, `Open Questions`, source-map strength, TDD coverage, standalone handoff prompts, and `packet.json` consistency.
 
-## Scaling
+The `plan-packet-validator` agent checks source accuracy, scope, enough implementation detail for a blind build agent, real TDD order, invented APIs or commands, and end-to-end acceptance criteria.
 
-Not every task needs all five phases. Match effort to complexity:
+## Rules
 
-- **Trivial** (rename, typo fix): Ask if a formal plan is even wanted. If yes, skip Phases 1-2, write a minimal plan.
-- **Small** (single-file change, clear scope): One Explore agent, skip Design phase, concise plan.
-- **Medium** (multi-file feature, some ambiguity): Full workflow, 1-2 agents per phase.
-- **Large** (cross-cutting change, architectural): Full workflow, max agents, thorough Review phase.
+- Write docs only.
+- Do not edit production code.
+- Do not run implementation commands.
+- Ask the user only for product choices that cannot be derived from local context.
+- Fold resolved answers into the packet. Never leave an `Open Questions` section.

package/skills/anthropic-plan/scripts/anthropic_plan_scripts_constants/validate_packet_constants.py

@@ -0,0 +1,33 @@
+"""Constants for the plan packet validator."""
+
+from __future__ import annotations
+
+ALL_REQUIRED_RELATIVE_PATHS: tuple[str, ...] = (
+    "README.md",
+    "packet.json",
+    "context/user-request.md",
+    "context/source-map.md",
+    "context/current-state.md",
+    "context/existing-patterns.md",
+    "context/constraints.md",
+    "context/glossary.md",
+    "spec/scope.md",
+    "spec/behavior.md",
+    "spec/interfaces.md",
+    "spec/data-flow.md",
+    "spec/failure-modes.md",
+    "spec/acceptance.md",
+    "implementation/strategy.md",
+    "implementation/steps.md",
+    "implementation/tdd-plan.md",
+    "implementation/file-plan.md",
+    "implementation/refactor-checkpoints.md",
+    "validation/validator-report.md",
+    "validation/deterministic-checks.md",
+    "validation/unresolved-risks.md",
+    "handoff/build-prompt.md",
+    "handoff/review-prompt.md",
+    "handoff/verification-commands.md",
+)
+MARKDOWN_FILE_SUFFIX: str = ".md"
+EXIT_CODE_VALIDATION_FAILED: int = 2

package/skills/anthropic-plan/scripts/test_validate_packet.py

@@ -0,0 +1,405 @@
+"""Tests for the plan packet validator."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+VALIDATOR_PATH = SCRIPTS_DIRECTORY / "validate_packet.py"
+
+
+def load_validator_module() -> ModuleType:
+    if str(SCRIPTS_DIRECTORY) not in sys.path:
+        sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+    spec = importlib.util.spec_from_file_location("validate_packet", VALIDATOR_PATH)
+    assert spec is not None
+    assert spec.loader is not None
+    validator_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(validator_module)
+    return validator_module
+
+
+def write_valid_packet(packet_directory: Path) -> None:
+    all_relative_paths = load_validator_module().required_relative_paths()
+    for each_relative_path in all_relative_paths:
+        target_path = packet_directory / each_relative_path
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        target_path.write_text(valid_markdown_for(each_relative_path), encoding="utf-8")
+
+    packet_payload = {
+        "schemaVersion": 1,
+        "slug": "add-login",
+        "repoRoot": str(packet_directory.parent.parent.parent),
+        "packetPath": str(packet_directory),
+        "sourceFiles": ["src/auth.py"],
+        "assumptions": ["No migration is needed."],
+        "validator": {"deterministic": "pending", "semantic": "pending"},
+    }
+    (packet_directory / "packet.json").write_text(
+        json.dumps(packet_payload, indent=2),
+        encoding="utf-8",
+    )
+
+
+def valid_markdown_for(relative_path: str) -> str:
+    if relative_path == "context/source-map.md":
+        return (
+            "# Source Map\n\n"
+            "| Source | Why it matters | Facts extracted | Plan implication |\n"
+            "|---|---|---|---|\n"
+            "| src/auth.py | Login flow entrypoint | Existing authenticate_user function handles password checks. | Reuse authenticate_user in the implementation. |\n"
+        )
+    if relative_path == "implementation/tdd-plan.md":
+        return (
+            "# TDD Plan\n\n"
+            "1. Failing test: add test_auth_login_success before production edits.\n"
+            "2. Production code: wire the existing authenticate_user call.\n"
+            "3. Refactor after green: remove duplicated setup.\n"
+        )
+    if relative_path == "implementation/steps.md":
+        return (
+            "# Steps\n\n"
+            "1. Test first: add login success coverage.\n"
+            "2. Production change: add the route handler; covered by test_auth_login_success.\n"
+        )
+    if relative_path == "handoff/build-prompt.md":
+        return (
+            "# Build Prompt\n\n"
+            "Use only this packet. Read README.md, then context/source-map.md, then implementation/steps.md. "
+            "Do not rely on prior chat history."
+        )
+    return f"# {relative_path}\n\nGrounded implementation detail for this packet file.\n"
+
+
+def run_validator(packet_directory: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(VALIDATOR_PATH), str(packet_directory)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_valid_packet_passes(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr
+    assert "packet validation passed" in validator_run.stdout
+
+
+def test_missing_required_file_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "spec" / "behavior.md").unlink()
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "missing required file: spec/behavior.md" in validator_run.stderr
+
+
+def test_placeholder_text_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "spec" / "scope.md").write_text("TODO: fill this in", encoding="utf-8")
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "placeholder text" in validator_run.stderr
+
+
+@pytest.mark.parametrize(
+    "template_placeholder_markdown",
+    [
+        "# <Plan Title>\n\nThis plan implements the feature.",
+        "This plan implements <feature name> for the <component> module.",
+        "| <path> | <reason> | <verified fact> | <implementation implication> |",
+    ],
+)
+def test_angle_bracket_placeholder_text_fails(
+    tmp_path: Path,
+    template_placeholder_markdown: str,
+) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "spec" / "scope.md").write_text(
+        template_placeholder_markdown,
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "spec/scope.md contains placeholder text" in validator_run.stderr
+
+
+@pytest.mark.parametrize(
+    "non_placeholder_markdown",
+    [
+        "<details>\n<summary>Notes</summary>\nGrounded detail.\n</details>",
+        "Type the annotation as `list[str]` and call `<command>` from a code span.",
+        "Reach the endpoint with `curl <url>` inside the inline code span.",
+        "The comparison `attempt_count < threshold` must hold before the retry.",
+        "The handler accepts a List<Item> of records.",
+        "Wrap the field in Optional<User> when it may be absent.",
+        "The cache stores an Array<string> of identifiers.",
+        "The lookup uses a Map<Key, Value> keyed by request id.",
+    ],
+)
+def test_inline_html_and_code_does_not_flag_placeholder(
+    tmp_path: Path,
+    non_placeholder_markdown: str,
+) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "spec" / "scope.md").write_text(
+        non_placeholder_markdown,
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr
+
+
+def test_open_questions_heading_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "validation" / "unresolved-risks.md").write_text(
+        "## Open Questions\n- Which database?",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "Open Questions" in validator_run.stderr
+
+
+def test_weak_source_map_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "context" / "source-map.md").write_text(
+        "# Source Map\n\nNo sources yet.\n",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "source-map.md must include source-grounded rows" in validator_run.stderr
+
+
+def test_missing_tdd_plan_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "implementation" / "tdd-plan.md").write_text(
+        "# TDD Plan\n\nImplementation can start directly.",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "tdd-plan.md must name failing tests" in validator_run.stderr
+
+
+@pytest.mark.parametrize(
+    "forbidden_phrase",
+    ["as discussed above", "from our chat", "previous conversation", "earlier in this thread"],
+)
+def test_handoff_prompt_depending_on_chat_history_fails(
+    tmp_path: Path,
+    forbidden_phrase: str,
+) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "handoff" / "build-prompt.md").write_text(
+        f"# Build Prompt\n\nUse the details {forbidden_phrase}.",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "build-prompt.md must stand alone" in validator_run.stderr
+
+
+def test_tdd_plan_with_red_only_as_substring_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "implementation" / "tdd-plan.md").write_text(
+        "# TDD Plan\n\nImplementation is required. Wire production code directly.",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "tdd-plan.md must name failing tests" in validator_run.stderr
+
+
+def test_tdd_plan_naming_red_step_passes(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "implementation" / "tdd-plan.md").write_text(
+        "# TDD Plan\n\n1. Red step: add the failing coverage.\n2. Green production code follows.",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr
+
+
+def test_packet_path_with_forward_slashes_matches_native_directory(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["packetPath"] = packet_directory.as_posix()
+    packet_file.write_text(json.dumps(packet_payload, indent=2), encoding="utf-8")
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr
+
+
+def test_packet_path_with_trailing_separator_matches_directory(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["packetPath"] = str(packet_directory) + "/"
+    packet_file.write_text(json.dumps(packet_payload, indent=2), encoding="utf-8")
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr
+
+
+def test_packet_path_mismatch_still_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["packetPath"] = str(packet_directory.parent / "different-slug")
+    packet_file.write_text(json.dumps(packet_payload, indent=2), encoding="utf-8")
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "packet.json packetPath must match the validated packet directory" in validator_run.stderr
+
+
+def test_source_map_with_bare_non_python_source_passes(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "context" / "source-map.md").write_text(
+        "# Source Map\n\n"
+        "| Source | Why it matters | Facts extracted | Plan implication |\n"
+        "|---|---|---|---|\n"
+        "| plan-packet.mjs | Workflow entry | Exports the run function. | Reuse the run shape. |\n",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr
+
+
+def test_source_map_with_only_version_number_row_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "context" / "source-map.md").write_text(
+        "# Source Map\n\n"
+        "| Source | Why it matters | Facts extracted | Plan implication |\n"
+        "|---|---|---|---|\n"
+        "| The login subsystem | We reviewed version 2.0 of the design | No file path named here | Build accordingly |\n",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "source-map.md must include source-grounded rows" in validator_run.stderr
+
+
+def test_source_map_data_row_naming_source_and_facts_passes(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "context" / "source-map.md").write_text(
+        "# Source Map\n\n"
+        "| Source | Why it matters | Facts extracted | Plan implication |\n"
+        "|---|---|---|---|\n"
+        "| src/auth.py | The source of truth for login | Key facts about hashing | Reuse it |\n",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr
+
+
+def test_has_source_table_row_keeps_grounded_row_with_source_and_facts_prose() -> None:
+    validator_module = load_validator_module()
+    source_map_text = (
+        "| Source | Why it matters | Facts extracted | Plan implication |\n"
+        "|---|---|---|---|\n"
+        "| src/auth.py | The source of truth for login | Key facts about hashing | Reuse it |\n"
+    )
+
+    assert validator_module.has_source_table_row(source_map_text) is True
+
+
+def test_has_source_table_row_skips_header_only_document() -> None:
+    validator_module = load_validator_module()
+    source_map_text = (
+        "| Source | Why it matters | Facts extracted | Plan implication |\n"
+        "|---|---|---|---|\n"
+    )
+
+    assert validator_module.has_source_table_row(source_map_text) is False
+
+
+def test_bullet_list_steps_without_test_contract_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "implementation" / "steps.md").write_text(
+        "# Steps\n\n"
+        "- Add the route handler\n"
+        "- Wire the database call\n",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 2
+    assert "implementation/steps.md has steps without a test or non-code reason" in validator_run.stderr
+
+
+def test_bullet_list_steps_naming_test_contract_passes(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_valid_packet(packet_directory)
+    (packet_directory / "implementation" / "steps.md").write_text(
+        "# Steps\n\n"
+        "- Test first: add login success coverage.\n"
+        "- Production change: add the route handler; covered by test_auth_login_success.\n",
+        encoding="utf-8",
+    )
+
+    validator_run = run_validator(packet_directory)
+
+    assert validator_run.returncode == 0, validator_run.stderr