Methodology

AI-First Development Methodology

What Is This

A structured development approach for AI agents. Every feature goes through a pipeline: idea → spec → architecture → tasks → implementation → documentation update. Each stage has automated validators and quality gates. QA and deploy are regular tasks in the tech-spec, not separate pipeline steps.

Core problems it solves:

• Context loss between sessions — distributed knowledge base persists across sessions
• Quality without human review — automated validators at every stage
• Scope creep — specs approved before coding starts
• Outdated agent knowledge — Context7 MCP fetches current library docs

---

Development Pipeline

The full path from idea to production. Each step has a command, a skill behind it, and validators.

Step 1: User Spec — /new-user-spec

What: Structured interview to capture requirements in human-readable form (in the user's language).

Process:

• Agent reads Project Knowledge files to understand the project
• Scans codebase for relevant code, patterns, integration points
• Runs 3 interview cycles with the user (general → code-informed → edge cases)
• interview-completeness-checker agent verifies coverage
• Creates user-spec.md from interview data → git commit draft
• 2 validators run in parallel (up to 3 iterations):
• userspec-quality-validator — document structure, acceptance criteria testability
• userspec-adequacy-validator — solution feasibility, over/underengineering
• Git commit after each validation round
• User approves → git commit approval (status: approved)

Output: work/{feature}/user-spec.md (status: approved)

Skill: user-spec-planning

Step 2: Tech Spec — /new-tech-spec

What: Technical architecture, decisions, testing strategy, implementation plan.

Process:

• Reads approved user-spec
• Researches codebase, checks dependencies, uses Context7 for external libraries
• Asks technical clarification questions
• Copies tech-spec template, edits sections in place → tech-spec.md with architecture (including Shared Resources for heavy objects like ML models, DB pools), decisions, testing strategy, brief Implementation Tasks (scope only — AC and TDD are added during task-decomposition) → git commit draft
• Implementation Tasks include Verify-smoke (executable checks: curl, python -c, docker) and Verify-user (manual UI/UX checks) fields where applicable
• Last two waves are always Audit Wave (3 parallel auditors: code, security, test) and Final Wave (QA + deploy)
• 5 validators run in parallel (up to 3 iterations):
• skeptic — detects non-existent files, functions, APIs (mirages)
• completeness-validator — bidirectional requirements traceability, over/underengineering, solution depth
• security-auditor — OWASP Top 10 review
• test-reviewer — test plan adequacy
• tech-spec-validator — template compliance, task quality, wave conflict detection
• Git commit after each validation round
• User approves → git commit approval (status: approved)

Output: work/{feature}/tech-spec.md (status: approved)

Skill: tech-spec-planning

Step 3: Task Decomposition — /decompose-tech-spec

What: Break tech-spec into atomic task files.

Process:

• For each Implementation Task in tech-spec, task-creator agent copies task template and fills it (parallel)
• Each task file expands brief tech-spec scope into: acceptance criteria, TDD anchor (from Testing Strategy), context files, skills, reviewers, wave, dependencies → git commit draft
• 2 validators run in parallel (up to 3 iterations):
• task-validator — template compliance, content quality
• reality-checker — validates against actual codebase (file existence, feasibility)
• Cross-task integration check: both validators re-run on all tasks together — catches shared resource conflicts, duplicate heavy resource init, hidden dependencies (max 2 extra iterations)
• Git commit after each validation round
• User approves → git commit approval

Output: work/{feature}/tasks/*.md (validated)

Skill: task-decomposition

Step 4: Implementation

Choose /do-task when: single task, manual control, debugging, iterating on one piece. Choose /do-feature when: multiple tasks ready, standard feature work, want parallel execution.

Two modes:

Mode A: Single Task — /do-task

One task per session. Suited for manual, controlled execution.

Process:

• Reads task file and all its Context Files
• Loads skills specified in task (e.g. code-writing, pre-deploy-qa, infrastructure-setup)
• Follows loaded skill workflow (TDD for code tasks, verification for QA tasks, etc.)
• Git commit implementation (code + tests pass)
• Runs reviewers specified in task (if any), up to 3 review iterations
• Git commit after each round of review fixes (tests pass)
• Writes entry to decisions.md, updates task status → done
• Git commit status + decisions

Skill: Loaded from task file (typically code-writing for code tasks)

Mode B: Full Feature — /do-feature

All tasks via agent teams. Team lead orchestrates waves of parallel work.

Process:

• Team lead reads tech-spec and all task files, builds execution plan
• Checks checkpoint.yml — if resuming after context compaction, skips completed waves (uses decisions.md as source of truth for what actually completed)
• Creates team via spawn_agent worker/explorer orchestration
• Executes tasks wave by wave:
• Spawns one agent per task (parallel within wave)
• Each teammate: follows loaded skill workflow, runs smoke verification if task has Verify-smoke (before reviews), commits code (tests pass), sends diff to reviewers, fixes findings with commits per round (max 3 rounds), commits review reports
• Each teammate writes decisions.md entry
• Lead commits status updates (task frontmatter + decisions.md) after wave completes, updates checkpoint.yml
• Audit Wave (always present): 3 auditors run in parallel (code-reviewer, security-auditor, test-reviewer) — review all feature code holistically. Issues found → lead spawns fixer agent, auditors become reviewers (max 3 fix rounds)
• Ad-hoc agents: when lead needs work outside planned tasks (fixing audit findings, escalations), assigns matching skill + reviewers based on work type
• Final Wave: QA (always), deploy + post-deploy (if applicable)
• Escalation: after 3 failed fix rounds — stop, report to user, write decisions.md entry, wait for decision
• User reviews results, team shuts down, checkpoint.yml deleted

Tasks can be code, user-action, deploy, config, or verification. Task nature is determined by its skill + description, not a separate type field.

Skill: feature-execution

Step 5: Done — /done

What: Finalize feature, update project knowledge, archive.

Process:

• Reads user-spec, tech-spec, decisions.md
• Updates affected Project Knowledge files (architecture.md, patterns.md, deployment.md, etc.)
• Moves work/{feature}/ → work/completed/{feature}/
• Commits changes

Skill: Loads documentation-writing skill for PK update rules

---

Project Structure

Dual Runtime: Claude Source, Codex Generated

The methodology is maintained in two compatible runtimes:

Claude source of truth:
~/.claude/                 # global methodology source
{project}/CLAUDE.md        # project instructions source
{project}/.claude/**       # project knowledge and project skills source

Codex generated runtime:
~/.codex/**                # generated global Codex runtime
{project}/AGENTS.md        # generated project instructions
{project}/.codex/**        # generated project Codex runtime

Rules:

• Edit Claude files by default: ~/.claude/**, CLAUDE.md, .claude/**.
• Do not manually edit generated Codex files unless explicitly debugging sync behavior.
• After changing global methodology files, run:

~/.claude/scripts/sync-to-codex.sh --apply

• After changing project docs or project skills, run:

~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply

• Project templates are dual-runtime. /init-project creates both Claude source files and Codex generated files.
• /init-project-knowledge, /done, documentation-writing, project-planning, infrastructure-setup, deploy-pipeline, commands, and docs-related skills update .claude/** first, then sync to .codex/**.
• Project pre-commit hooks run project sync automatically when staged .claude/** changes.
• The global ~/.claude pre-commit hook runs global sync automatically when staged methodology files change.

MCP is handled separately because it is private runtime access, not documentation:

~/.claude/scripts/sync-mcp-to-codex.sh --apply --prune

This imports Claude/project .mcp*.json into local private Codex config (~/.codex/mcp-imported/ and a managed block in ~/.codex/config.toml). MCP configs, auth files, credentials, sessions, caches, and runtime state are never committed.

Project Knowledge — the Knowledge Base

All project documentation lives in .claude/skills/project-knowledge/references/. This is the single source of truth for everything about the project.

4 core + optional files:

| File | Content | |------|---------| | project.md | Purpose, audience, core features, scope | | architecture.md | Tech stack, structure, dependencies, data model | | patterns.md | Code conventions, git workflow, testing, business rules | | deployment.md | Platform, env vars, CI/CD, monitoring | | ux-guidelines.md | UI language, tone, domain glossary (optional) |

Features and roadmap live in the project backlog (external to PK).

CLAUDE.md is minimal. It contains only the project name, a reference to project-knowledge skill, methodology overview, and default branch. All real information lives in Project Knowledge files.

project-planning skill creates PK from scratch in new projects via interview (/init-project-knowledge).

documentation-writing skill manages existing PK: audits, updates, checks consistency. /done command uses it to update PK after feature completion.

Work Items

work/{feature}/
├── user-spec.md          # Requirements (user's language, for human)
├── tech-spec.md          # Architecture (English, for agent)
├── decisions.md          # Decisions made during implementation
├── tasks/
│   ├── 1.md              # Atomic task files
│   ├── 2.md
│   └── 3.md
└── logs/                 # Working logs (interview, research, reviews)

Completed features are archived to work/completed/{feature}/.

Global Structure ~/.claude/

~/.claude/
├── skills/               # Skills (methodology, workflow, quality)
├── agents/               # Agents (validators, reviewers, creators)
├── commands/             # Slash commands
├── shared/               # Templates, scripts, interview plans
├── hooks/                # Automation hooks
└── CLAUDE.md             # Global instructions

---

Key Principles

Commit Strategy

Commit after each step where the repository state is stable and meaningful. Not after every action — after each result.

• Planning stages (user-spec, tech-spec, tasks): draft commit → validation round commits → approval commit
• Single task execution (do-task): implementation commit (tests pass) → review fix commits (tests pass) → status/decisions commit
• Feature execution (do-feature): teammates commit code + review fixes, lead commits statuses per wave
• Finalization (done): single commit with PK updates + archive

Spec-Driven Development

Write specifications before code. The hierarchy: User Spec → Tech Spec → Tasks → Code. Code starts only after specs are approved.

Validation at Every Stage

• User spec: 2 validators (quality + adequacy)
• Tech spec: 5 validators (skeptic + completeness + security + test + template/task-quality)
• Tasks: 2 validators (template + reality)
• Code: 3 reviewers (code + test + security) + smoke verification (API calls, library checks, MCP tools, local runs)
• Audit Wave: 3 auditors (code + security + test) review all feature code holistically after implementation waves
• QA tasks: pre-deploy QA (tests + acceptance criteria), post-deploy QA (verification on live environment)

Max 3 fix iterations at each stage.

Project Knowledge as Single Source of Truth

Project documentation = .claude/skills/project-knowledge/references/. CLAUDE.md stays minimal — just a pointer. The /done command updates PK after every feature. The documentation-writing skill audits PK for bloat and quality.

Just-In-Time Context

Agent reads only what's needed for current task, not everything. Task files list their Context Files explicitly.

Context7 for Library Docs

Agent uses Context7 MCP to fetch current library documentation instead of relying on training data. Used during tech-spec research and code implementation.

Checkpoint Recovery

Feature execution persists state to checkpoint.yml after each wave. A SessionStart(compact) hook detects context compaction during long feature executions and injects recovery context — the lead resumes from the next pending wave using checkpoint + decisions.md as source of truth.

Language

User-facing artifacts (chat, plans, interviews, validator summaries, user-spec, README) are written in the language the user writes in. Technical artifacts (tech-spec, tasks, code, code comments, AI prompts, internal logs) and document section headers stay in English as stable anchors for validators.

The user's language is declared once in the instruction file — ~/.claude/CLAUDE.md for Claude and ~/.codex/AGENTS.md for Codex (or per-project CLAUDE.md / AGENTS.md). Skills and agents resolve "the language the user writes in" from that declaration rather than guessing per message, so output stays consistent even for subagents that never see the chat. To change the language, edit only that one line.

---

Skills Ecosystem

Planning Skills

| Skill | Purpose | |-------|---------| | project-planning | New project: interview → project knowledge docs (project.md, architecture.md, etc.) | | user-spec-planning | Feature requirements: interview → user-spec.md | | tech-spec-planning | Architecture: research → tech-spec.md | | task-decomposition | Decompose tech-spec into atomic task files |

Execution Skills

| Skill | Purpose | |-------|---------| | code-writing | TDD cycle: plan → tests → code → review | | prompt-master | LLM prompt engineering: write, improve, verify prompts | | feature-execution | Team lead dispatches agents by wave; teammates commit own code, lead commits statuses | | pre-deploy-qa | Pre-deploy acceptance testing: tests + acceptance criteria | | post-deploy-qa | Post-deploy verification on live environment via MCP tools |

Quality & Review Skills

| Skill | Purpose | |-------|---------| | code-reviewing | 11-dimension code review methodology (incl. Resource Management) | | security-auditor | OWASP Top 10 security analysis | | test-master | Testing strategy: when to use which tests |

Meta Skills

| Skill | Purpose | |-------|---------| | methodology | This skill — how the process works | | documentation-writing | Manage Project Knowledge files | | skill-master | Create and maintain quality skills | | infrastructure-setup | Framework init, Docker, pre-commit hooks, testing setup | | deploy-pipeline | CI/CD pipelines, deployment config, automated deploy | | prompt-master | Effective prompts for LLMs (also an execution skill) | | skill-tester | Full skill testing cycle: design scenarios, run, grade, report |

---

Agents

Agents are isolated subprocesses with fresh context. They receive input, do one job, return structured output.

Validators (run during spec/task creation)

• userspec-quality-validator — document quality and completeness
• userspec-adequacy-validator — so

…

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.