Full Development Workflow

Develop a feature or fix end-to-end with TDD, testing, self-review, and clean commit history.

Instructions

Phase 0: Understand the Task

1. Get the task from the arguments provided when this skill is invoked: either a GitHub Issue number or a task description.
2. Check for spec (issue numbers only): look for .claude/specs/{issue-number}-*.md.
   • If found with Status: approved: read it. Report: "Using approved spec: {filename}". The sova-develop skill step will follow this spec as its primary guide.
   • If found with Status: draft: warn the user: "Draft spec exists at {filename} but is not approved. Run the sova-spec skill {issue} to review and approve it, or proceed without spec guidance." Wait for user confirmation before continuing (when running headless, with no user to confirm, proceed without spec guidance and say so in the summary).
   • If not found: continue silently. Specs are optional; not every task needs one.
3. If it's an issue number, fetch details. When an approved spec was found in step 2, it already encodes the task intent in distilled form, so omit body and fetch only the fields this phase still needs (claiming, branch naming, labels):

   # No approved spec:
   gh issue view <ISSUE_NUMBER> --json number,title,body,labels,milestone
   # Approved spec found in step 2:
   gh issue view <ISSUE_NUMBER> --json number,title,labels,milestone

4. Claim the issue (GitHub Issues only):

   # Assign to self
   gh issue edit <ISSUE_NUMBER> --add-assignee @me

   If the project uses a GitHub Projects board, move the issue to "In Progress".
5. Read the project's CLAUDE.md and AGENTS.md for conventions and patterns.
6. Read agent memory files if they exist:
   • .claude/agent-memory/MEMORY.md and .claude/agent-memory/common-mistakes.md
   • The cookbook: when .claude/agent-memory/cookbook/ exists, read its README.md index and then only the domain files for the modules this work touches (the whole cookbook is too large to load); otherwise read .claude/agent-memory/cookbook.md
7. Identify which module(s) this work touches and read relevant source code.
8. Check current branch: if on main/master, create a feature branch before developing, the same way the sova-new-feature skill does (in a dedicated worktree when the project keeps branches under .claude/worktrees/, so the primary checkout stays on the base branch):

   BRANCH=$(git branch --show-current)
   if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
     echo "On main branch. Create a feature branch before developing."
   fi

Phase 1: Develop (TDD)

Follow the sova-develop skill workflow:

1. Write tests first: define expected behavior before implementation.
2. Implement the solution: follow existing codebase conventions.
3. Scout check: for every file touched, fix pre-existing issues you notice (failing tests, lint warnings, dead code, obvious bugs). Keep fixes small and low-risk.
4. Run the project-specific build steps from the sova-develop skill's Step 5 (CSS rebuilds, static cache version bumps, translation catalogs) when your change calls for them.
5. Run the full CI-equivalent checks: make check. It is only as complete as the project configured it: if make check is not the same target CI runs, also run the CI steps it omits (read the CI workflow file to list them).
6. If any check fails, fix and re-run (up to 3 attempts).

Phase 2: Self-Review

Follow the sova-review skill workflow:

1. Review your own diff: git diff
2. Check for:
   • Bugs, edge cases, off-by-one errors
   • Missing test coverage
   • Security concerns
   • Code style consistency with the rest of the module
   • Unnecessary changes or leftover debug code
3. Address all findings (fix or acknowledge with justification).
4. Re-run tests after fixes.

Phase 3: Organize Commits

Follow the sova-rearrange-commits skill approach:

1. Separate concerns: schema/model changes, core logic, tests, config in distinct commits.
2. Each commit should be self-contained and reviewable on its own.
3. Commit message format: type(scope): description
   • Types and scopes: only those the project's commit format invariant or AGENTS.md lists (commonly feat, fix, refactor, test, docs, chore, ci); never invent one such as perf, since pre-push hooks reject it
   • Example: feat(auth): add token refresh endpoint
4. NEVER create a single monolithic commit with all changes.
5. Commit messages should explain the 'why', not just the 'what'.

Phase 4: Summary

Write a file at .agent-summary.md in the working directory with:

• Big picture: 3-5 sentence narrative explaining the problem, why it matters, and why this approach. Written for someone unfamiliar with the ticket.
• What changed: Brief description of all changes.
• How it worked before / How it works now: Behavior delta.
• Manual test instructions: Exact commands, expected outputs, edge cases, what success/failure looks like.
• Files changed: List with one-line descriptions.

Workflow Chain

This command orchestrates:

1. the sova-develop skill: implement with TDD
2. the sova-test skill: verify linter + tests pass
3. the sova-review skill: self-review and auto-fix
4. the sova-rearrange-commits skill: organize into logical commits

After this command completes, run the sova-pr skill to create the pull request.

Rules

• Follow patterns from the project's existing code and CLAUDE.md/AGENTS.md
• NEVER use emojis in any output