Code Writing

Code Writing

Phase 1: Preparation

1. Parse Requirements

• Extract what needs to be built from user message or passed acceptance criteria
• Clarify ambiguities — ask user if unclear
• Formulate acceptance criteria (what "done" looks like)

1. Read Project Context (Graceful)

Working on a task? Read all files listed in the task's "Context" section — it already specifies everything needed.

Standalone (no task file)? Read (skip if missing):

• .claude/skills/project-knowledge/references/project.md — project overview
• .claude/skills/project-knowledge/references/architecture.md — system structure
• .claude/skills/project-knowledge/references/patterns.md — project conventions

Then read .claude/skills/project-knowledge/SKILL.md (if exists). Consider which domain-specific guides are relevant to your task and read those (e.g., architecture.md Data Model section for DB work, ux-guidelines.md for UI tasks).

No project patterns? Apply baseline from [universal-patterns.md](references/universal-patterns.md) — naming, error handling, structure.

1. Analyze & Review Approach

Before coding, output your findings:

• Grep for usages of code to be modified
• Read all files that will be changed
• Verify solution follows project patterns (or universal patterns)
• Identify existing code that can be reused
• If modifying existing code, run existing tests for the area to establish baseline

If concerns → discuss with user before proceeding.

Checkpoint: List completed preparation steps before moving to implementation.

Phase 2: Implementation (TDD)

1. Write Tests First

Before writing tests, read [testing-guide.md](references/testing-guide.md) — when to write which test type, test structure.

• Write tests for: business logic, validations, transforms, error handling. Skip trivial code without logic (simple getters, one-liners, configs)
• Write tests for requirements and edge cases
• Tests should fail initially (no implementation yet)
• One test = one scenario, test behavior not implementation
• If mocking >3 dependencies → wrong test type, use integration test

1. Write Code

• Implement to pass tests
• Follow project patterns (from Phase 1) or apply baseline from [universal-patterns.md](references/universal-patterns.md)
• Use env vars for secrets, validate inputs at boundaries
• Handle edge cases, comment WHY not WHAT

1. Run Tests

• All new tests pass
• Fix any failures

Checkpoint: List implemented functionality and test results.

Phase 3: Post-work

1. Run Lint/Format

• Run project's linter and formatter before reviews

1. Run Relevant Tests

• Tests for files changed
• Tests mentioned in task (if applicable)
• Save full test suite for end of feature

1. Smoke Verification (if task has Verification Steps → Smoke or User)

Execute each command from the Smoke section. Record results in decisions.md Verification section. If a check fails — fix the code before proceeding to reviews. If the task has User checks — ask the user to verify, wait for confirmation.

Smoke catches integration bugs that mocked tests miss: real API responses, library initialization, config validity.

1. Run Reviews (launch in parallel)

Reviewer selection:

• Working on a task file → run reviewers from the task's "Reviewers" section
• Standalone (no task file) → default: code-reviewer, security-auditor, test-reviewer

For each reviewer:

1. Spawn subagent via spawnagent (subagenttype = reviewer name, e.g. code-reviewer)
2. Pass: git diff of changes, path to task file, path to tech-spec, path to user-spec
3. Reviewer loads its own skill automatically (via agent frontmatter skills:)
4. Report path: from the task's "Reviewers" section (or logs/working/ if standalone)

Reviewers write JSON reports to logs/working/task-{N}/{reviewer-name}-{round}.json. {N} = task number from task file; "standalone" if no task file. On re-review: new file with incremented round number, old file stays.

1. Process Findings

Evaluate each finding on merit — severity is metadata, not a filter. A valid minor fix still improves quality. Reason: skipping valid findings silently degrades the codebase over time.

For each finding:

• Valid, improves code → apply (any severity: critical, major, minor, low)
• Disagree or uncertain → discuss with user (explain reasoning)
• Out of scope → skip, note in findings log

Produce a findings log: | # | Source | Severity | Finding | Action | Reason | Each finding appears in this table — transparent decision trail.

After applying fixes → re-run tests → re-run the reviewer(s) that reported them. Limit: 3 review iterations. If findings remain after round 3 → ask user. Reason: fixes can introduce new issues — a second pass catches regressions.

Checkpoint: List post-work steps completed.

Self-Verification

Verify each item before marking complete. If any item fails, return to the relevant phase.

• [ ] All phases completed (Preparation, Implementation, Post-work)
• [ ] Tests pass
• [ ] Smoke verification executed (if task had Smoke/User checks)
• [ ] Each reviewer finding evaluated and logged
• [ ] Findings log table produced
• [ ] Review JSON reports saved to logs/working/task-{N}/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pavel-molyanov
• Source: pavel-molyanov/molyanov-ai-dev
• License: MIT

Install and usage instructions live in the source repository linked above.