diff --git a/skills/code-architect/SKILL.md b/skills/code-architect/SKILL.md index 2ccfcc0..2f33db2 100644 --- a/skills/code-architect/SKILL.md +++ b/skills/code-architect/SKILL.md @@ -17,6 +17,31 @@ These bias toward caution over speed — use judgment on trivial tasks. - **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. - **Goal-driven** — turn the task into a concrete success check and iterate until it passes. +## Feature-dev handoff contract + +When dispatched by `feature-dev`, follow this contract and choose one approach within the assigned lens. + +### Required inputs + +- `ASSIGNMENT_ID` and assigned lens +- Approved requirements and exclusions +- Phase 3 decisions +- Exploration synthesis and evidence +- Key files + +### Required output + +Start with `Status: complete | partial | blocked`, then provide: + +- `ASSIGNMENT_ID` +- Scope inspected and scope not inspected +- Assumptions +- Assigned lens +- Requirements-to-components traceability +- Out-of-scope list +- Test plan tied to build steps +- Unresolved blockers + ## Core process ### 1. Codebase pattern analysis diff --git a/skills/code-explorer/SKILL.md b/skills/code-explorer/SKILL.md index ad93e75..1073766 100644 --- a/skills/code-explorer/SKILL.md +++ b/skills/code-explorer/SKILL.md @@ -12,6 +12,31 @@ You are an expert code analyst specializing in tracing and understanding feature Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers. +## Feature-dev handoff contract + +When dispatched by `feature-dev`, follow this contract. + +### Required inputs + +- `ASSIGNMENT_ID` and focus +- Objective +- Requirements and exclusions +- Repository and path scope +- Known context + +### Required output + +Start with `Status: complete | partial | blocked`, then provide: + +- `ASSIGNMENT_ID` +- Scope inspected and scope not inspected +- Focus conclusion +- Entry points and execution flow with `file:line` references +- Dependencies +- Extension points +- Unresolved questions +- 5–10 essential files, or an explanation of why fewer exist + ## Analysis approach ### 1. Feature discovery diff --git a/skills/feature-dev/SKILL.md b/skills/feature-dev/SKILL.md index ead5bea..dc95174 100644 --- a/skills/feature-dev/SKILL.md +++ b/skills/feature-dev/SKILL.md @@ -25,6 +25,39 @@ These bias toward caution over speed — use judgment on trivial tasks. - **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it. - **Goal-driven** — turn the task into a concrete success check and iterate until it passes. +## Orchestration contract + +Every child assignment must contain exactly this assignment envelope: + +```text +ASSIGNMENT_ID: +PHASE: +SPECIALIST: +OBJECTIVE: +SCOPE: +FOCUS: +REQUIREMENTS: +EXCLUSIONS: +PRIOR_INPUTS: +REQUIRED_OUTPUT: +COMPLETION_CRITERIA: +``` + +Require each child response to start with `Status: complete | partial | blocked`, repeat `ASSIGNMENT_ID`, report covered and uncovered scope, include the phase-specific evidence, and list errors or blockers. + +Maintain a coverage ledger containing assignment, focus, status (`pending | valid | blocked | failed | local-fallback`), dispatch count, resume count, retry count, evidence received, uncovered items, and fallback action. + +Use this recovery order: + +1. Dispatch independent assignments in parallel. +2. If parallel dispatch is unavailable, dispatch only unfinished assignments serially. +3. For a transient timeout, rate-limit, or transport failure, retry it as a fresh task at most once. +4. Validate every response against `REQUIRED_OUTPUT` and `COMPLETION_CRITERIA`. +5. Resume the same child at most once for incomplete or malformed output, naming missing fields. +6. Permission denial does not consume the transient retry. +7. If task dispatch is unavailable or denied, a non-transient failure occurs, or recovery is exhausted, perform the assignment in the parent using the same contract. +8. Preserve valid sibling results, mark fallback usage, and disclose degraded execution in the final summary. + ## Phase 1: Discovery Goal: Understand what needs to be built. @@ -80,9 +113,21 @@ Goal: Build the feature. 1. Wait for approval. 2. Re-read all relevant files identified earlier. -3. Implement following the chosen architecture. -4. Strictly follow codebase conventions (naming, style, error-handling patterns). -5. Update todos as you progress. +3. Before editing, capture the implementation baseline: + + ```bash + git rev-parse HEAD + git status --short + git diff + git diff --cached + git ls-files --others --exclude-standard + ``` + + Retain before-content for every dirty or untracked path the implementation may touch. +4. Implement following the chosen architecture. +5. Strictly follow codebase conventions (naming, style, error-handling patterns). +6. After implementation, capture the same inventory and derive an implementation delta containing the baseline commit, pre-existing change ledger, implementation commits, exact changed paths, and staged/unstaged/untracked provenance. If Git is unavailable, use a file-level before/after ledger and label that limitation. +7. Update todos as you progress. ## Phase 6: Quality review diff --git a/tests/feature-dev-orchestration.test.mjs b/tests/feature-dev-orchestration.test.mjs new file mode 100644 index 0000000..5111947 --- /dev/null +++ b/tests/feature-dev-orchestration.test.mjs @@ -0,0 +1,54 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const REPO = process.env.REPO || process.cwd(); +const readSkill = (name) => readFileSync(join(REPO, "skills", name, "SKILL.md"), "utf8"); +const feature = readSkill("feature-dev"); +const explorer = readSkill("code-explorer"); +const architect = readSkill("code-architect"); + +test("feature-dev defines assignments and a coverage ledger", () => { + for (const field of [ + "ASSIGNMENT_ID", "PHASE", "SPECIALIST", "OBJECTIVE", "SCOPE", + "FOCUS", "REQUIREMENTS", "EXCLUSIONS", "PRIOR_INPUTS", + "REQUIRED_OUTPUT", "COMPLETION_CRITERIA", + ]) assert.ok(feature.includes(field), `missing ${field}`); + assert.match(feature, /coverage ledger/i); + assert.match(feature, /pending.*valid.*blocked.*failed.*local-fallback/is); +}); + +test("feature-dev bounds recovery and preserves valid sibling results", () => { + assert.match(feature, /resume the same .* at most once/is); + assert.match(feature, /transient .* retry .* at most once/is); + assert.match(feature, /permission denial.*does not consume.*retry/is); + assert.match(feature, /parallel dispatch.*unavailable.*serial/is); + assert.match(feature, /task dispatch.*(unavailable|denied).*parent/is); + assert.match(feature, /preserve.*valid.*sibling/is); + assert.match(feature, /degraded execution/i); +}); + +test("feature-dev captures the complete before-state before implementation", () => { + for (const command of [ + "git rev-parse HEAD", "git status --short", "git diff", + "git diff --cached", "git ls-files --others --exclude-standard", + ]) assert.ok(feature.includes(command), command); + assert.ok( + feature.indexOf("git rev-parse HEAD") < feature.indexOf("Implement following the chosen architecture"), + "baseline precedes edits", + ); + assert.match(feature, /pre-existing change ledger/i); + assert.match(feature, /implementation delta/i); +}); + +test("explorer and architect implement the feature-dev handoff", () => { + for (const [name, skill] of [["code-explorer", explorer], ["code-architect", architect]]) { + assert.match(skill, /Feature-dev handoff contract/i, name); + assert.match(skill, /Required inputs/i, name); + assert.match(skill, /Required output/i, name); + assert.match(skill, /Status: complete \| partial \| blocked/i, name); + assert.match(skill, /ASSIGNMENT_ID/i, name); + assert.match(skill, /scope inspected/i, name); + } +});