rafaie/codex_home/implement-feature

1) Read project AGENTS.md, codex.toml (if present), and target work item folder spec/features/<work-id>-<slug>/.

• <work-id> must use S-<stream>-<nnn> (example: S-core-001) for new work.
• Read feature.md, implementation.md, test-plan.md, test-results.md, and status.md when present.
• For legacy single-file specs, read the matching file under spec/features/.

2) Convert acceptance criteria into a checklist.

• Preserve stable IDs such as AC-1, AC-2, and map implementation/test evidence to them.
• Read the expected-red baseline from test-results.md; unexplained pre-existing failures are blockers.

3) Implement iteratively, one AC at a time:

• Make the smallest change to satisfy one criterion
• Add/adjust tests
• Add or update Google-style docstrings for new/changed public APIs, CLI entrypoints, data models/schemas, provider/client wrappers, integration boundaries, non-trivial private helpers, and shared test fixtures.
• Do not add docstrings that only restate the function name.
• Run the narrowest AC-scoped tests first, then the quick command (test_quick, else test, else uv run pytest -q).
• Known red tests for later ACs may remain only while they are documented and unrelated to the current AC.

4) Run quick checks plus smoke at required milestones when smoke applicability is required:

• Run milestone smoke in offline mode by default; the immediately following ship-feature run is the canonical live-default smoke owner.
• Use live milestone smoke only when validating provider-specific behavior is necessary to complete an AC, and record the reason/cost boundary.
• End of the final AC, as implementation evidence rather than the canonical ship run
• Any change to core/shared modules
• Any CLI, API, schema, or I/O behavior change
• Do not run smoke when test-plan.md records not_applicable with a valid non-runnable rationale.

5) Implementation-complete rule:

• All checklist items are checked, and
• AC-scoped and quick checks pass, and
• required milestone smoke passes with evidence artifacts.
• If an item is blocked/deferred, leave it unchecked and record reason, owner/next step, and follow-up work item ID.

6) Update work item docs:

• implementation.md: implementation log, files changed, key decisions/trade-offs
• test-results.md: commands run + outcomes
• status.md: current status, blockers, next action
• feature.md: only update scope/AC/design if reality changed

7) Include docstring changes or intentional omissions in implementation.md when API-facing code changed. 8) Include smoke evidence path (artifacts/smoke/...) in implementation.md or test-results.md when smoke runs. 9) If checks fail, invoke debug-loop. 10) Record user-facing and architecture documentation impact for ship-feature; do not invoke docs-update here. 11) End by recommending Run $ship-feature <work-id> for the canonical full checks and final evidence.