ship-issue

Ship Issue

Implement exactly one local issue file from docs/issues/ without handholding.

Contract

• Accept one issue path.
• Process only issues marked AFK.
• If the issue is HITL, stop immediately and say it needs a design/grilling pass.
• Do not ask product, design, or implementation questions.
• Infer from the issue, parent PRD, CONTEXT.md, ADRs, tests, and existing code.
• Stop only for true blockers: missing credentials, impossible test environment, destructive migration risk, contradictory requirements, or failing checks.
• Commit automatically only after the required checks pass.

1. Scope

1. Read the issue file.
2. Read the parent PRD when the issue has a Parent section.
3. Follow ../grill-with-docs/DOMAIN-AWARENESS.md before exploring the codebase.
4. Inspect git status --short and record pre-existing dirty files.
5. Identify the smallest behavior that satisfies the acceptance criteria.

Do not broaden the issue. If work is bigger than the issue, ship the smallest valid slice and create follow-up issues for the rest.

2. Control context

Main agent owns scope, edits, tests, staging, and commit. Use subagents only for bounded side work: explorer for context scouting, review, or architecture scouting; worker only for a disjoint patch with explicit file ownership.

Do not delegate the immediate blocker or duplicate work. Integrate subagent results yourself and discard anything outside issue scope.

3. TDD

Use the ../tdd/SKILL.md workflow: one public behavior test, expected failure, minimum implementation, repeat, then refactor only while green.

Prefer tests that survive refactors. Avoid internal mocks unless the public seam is an external dependency.

4. Review and fix

Look for bugs, regressions, missing tests, and risky assumptions. Fix every valid finding and rerun affected tests after each fix group.

5. Architecture

Use ../improve-codebase-architecture/SKILL.md. Implement improvements when they:

• are directly discovered while implementing this issue,
• are covered by or naturally adjacent to this issue's tests,
• are limited to files already touched or their immediate collaborators,
• preserve behavior unless the issue explicitly requires behavior change.

If an opportunity exceeds this blast radius, create a follow-up issue and link it from the current issue. Run a second review pass after architecture changes.

6. Verify

Before committing, targeted tests, added/changed tests, nearest suite, and clear format/lint/typecheck commands must pass.

Run the full suite when documented or reasonably bounded. If required checks cannot pass, stop before staging or committing and report the blocker.

7. Update issue

• Check off acceptance criteria that are directly satisfied.
• Add ## Implementation Notes with brief assumptions, design notes, and any follow-up issue links.
• Add ## Verification with the exact commands that passed.
• Add ## Status with Complete in this commit.

8. Commit

Stage only changes made for this issue. Never stage unrelated pre-existing dirty files.

Use ../commit/SKILL.md to create the commit with a meaningful Conventional Commits body, Tested: trailers, and Refs: pointing to the issue file.