| name | get-started |
| description | Start work on a GitHub issue using the Issue Implementation Workflow (Validate → Plan → Implement). Use when beginning work on an issue, switching issues, or resuming after a session break. |
Get Started: Issue Workflow
Execute the project's Issue Implementation Workflow for GitHub issue $ARGUMENTS.
Delegate to (do not duplicate): /commit when ready to commit; /pr when ready for PR; temp-files.mdc for tmp/ structure. Parse the issue number from patterns like fix issue #123, issue #45, #123, or 123. If no number is found, list open issues and ask the user to select one.
Purpose
Align on the Validate → Plan → Implement process before implementation or planning. Ensures workflow steps are loaded into context.
Scratch Files and Continuation
Use the project's tmp/ directory for all scratch files. Enables continuation between sessions.
| File Path | Purpose |
|---|
tmp/github/issue-descriptions/issue-NNN.md | Cached issue body from gh issue view NNN |
tmp/github/progress/issue-NNN-workflow.md | Workflow state: phase, decisions, validation results, next steps |
tmp/github/progress/issue-NNN-plan.md | Implementation plan (Phase 2 output) |
tmp/github/issue-comments/issue-NNN-close.md | Draft close comment when closing obsolete issues |
Continuation: At start, check if tmp/github/progress/issue-NNN-workflow.md exists. If it does, read it to load phase and next steps before continuing. Update after each step.
Writing to GitHub
Significant updates must be written to the GitHub issue so stakeholders see progress. Do not keep them only in tmp/.
| When | What to post | How |
|---|
| Phase 1: Issue refinement | Refined acceptance criteria, out-of-scope, validation findings | gh issue comment NNN --body-file tmp/github/issue-comments/issue-NNN-refinement.md |
| Phase 2: Plan complete | Implementation plan with checklists (tasks, test strategy) | gh issue comment NNN --body-file tmp/github/issue-comments/issue-NNN-plan.md |
| Phase 3: Milestones | Completed subtasks, test results | gh issue comment NNN --body-file ... when logical milestones are reached |
| Phase 3: Acceptance criteria | Update checkboxes when criteria are verified complete | Fetch body, edit - [ ] → - [x], then gh issue edit NNN --body-file tmp/github/issue-descriptions/issue-NNN.md |
Draft first in tmp/github/issue-comments/, then post when content is ready. For acceptance criteria: only mark [x] when verified and validated, not just implemented. Update the issue body so the main issue reflects actual status.
Prerequisites
- GitHub CLI (
gh): gh auth login if not authenticated
- PowerShell users: Use
; instead of && for chained commands
- Quality gate:
uv sync --group dev and uv run pytest pass before starting
Required Context Loading
CRITICAL: Before executing any phase, load:
- docs/portfolio/ISSUE_IMPLEMENTATION_WORKFLOW.md — full 3-phase workflow
- CLAUDE.md — project conventions, build commands, architecture
- .cursor/rules/branch-policy.mdc — branch naming; all work merges via PR
- .claude/skills/merge-via-pr/SKILL.md — never commit deliverable work on
main
- .claude/skills/plan-branch-strategy/SKILL.md — if on
main, branch before first file edit (uncommitted changes follow git checkout -b)
- .cursor/rules/github-integration.mdc — optional; branch naming, gh CLI
Execution Workflow
Step 1: Parse Input
- Extract issue number from $ARGUMENTS (patterns:
#(\d+), issue\s*#?\s*(\d+))
- If found → proceed to Step 2
- If not found → go to Step 6 (list open issues, ask user to select)
- Continuation: If
tmp/github/progress/issue-NNN-workflow.md exists, read it first
Step 2: Load Context
- Read docs/portfolio/ISSUE_IMPLEMENTATION_WORKFLOW.md
- Read CLAUDE.md
- Continuation: Read tmp/github/progress/issue-NNN-workflow.md if it exists
Step 3: Fetch Issue
gh issue view <NNN>
- Write: Save output to
tmp/github/issue-descriptions/issue-NNN.md
- Write: Create/update
tmp/github/progress/issue-NNN-workflow.md with issue number, phase, status
If gh fails: Prompt "Run gh auth login" and stop.
If issue not found: Report and suggest gh issue list --state open.
Step 4: Phase 1 — Validate
- 1.1 Check: Goal relevant? Acceptance criteria clear and testable? Out-of-scope explicit?
- 1.2 Search codebase; check recent commits and merged PRs
- 1.3 Research tooling and best practices
- Write: Update
tmp/github/progress/issue-NNN-workflow.md with validation results
- If refinement done: Draft to
tmp/github/issue-comments/issue-NNN-refinement.md, then gh issue comment NNN --body-file tmp/github/issue-comments/issue-NNN-refinement.md
If obsolete or already done:
- Draft close comment to
tmp/github/issue-comments/issue-NNN-close.md
- Suggest
gh issue close NNN --comment "Duplicate of #X" or similar
- Stop
If valid → proceed to Step 5
Step 5: Phase 2 — Plan and (Optionally) Implement
- If on
main: create a branch before editing: git checkout main; git pull origin main; git checkout -b feature/NNN-short-description (or task/, bug/, hotfix/, chore/…). If you already have local edits on main, run git checkout -b feature/NNN-short-description once — your working tree moves to the new branch. See plan-branch-strategy.
- Review architecture (CLAUDE.md, docs/technical/)
- Decide test strategy
- Assign:
gh issue edit NNN --add-assignee @me
- Write: Save plan to
tmp/github/progress/issue-NNN-plan.md
- Write: Update
tmp/github/progress/issue-NNN-workflow.md with phase, branch, plan summary, next steps
- GitHub: Draft plan (with checklists) to
tmp/github/issue-comments/issue-NNN-plan.md, then gh issue comment NNN --body-file tmp/github/issue-comments/issue-NNN-plan.md
- If user requested "implement" or "fix": proceed to Phase 3 (small steps, test after each, quality gate before commit)
- If user requested "plan" only: present plan and stop
Step 6: No Issue Specified
- Load workflow context (Step 2)
- Run
gh issue list --state open --limit 20 and display
- Summarize three-phase workflow
- Write (optional): Save list to
tmp/github/progress/open-issues.md
- Ask user to select:
/get-started fix issue #N or create new issue
Phase 3 Continuation
During implementation, keep tmp/github/progress/issue-NNN-workflow.md updated:
- After each logical step: what was done, tests run, next concrete action
- Next agent reads this file and resumes
Error Handling
| Condition | Action |
|---|
gh auth status fails | Prompt gh auth login |
| Issue #NNN not found | Report, suggest gh issue list --state open |
| Already on feature branch | Note it; validate and plan; user may want to switch |
| Quality gate fails | uv sync --group dev and retry |
Success Criteria
- Workflow context loaded
- Issue fetched and displayed
- Phase 1 Validate completed (or close if obsolete)
- Phase 2 Plan started (branch created, plan posted to GitHub)
- Scratch files updated for continuation
- Optionally Phase 3 begun
References
