methodology

name	methodology
description	AI-First development methodology: spec-driven pipeline, project structure, skills/agents ecosystem, quality gates. Use when: "изучи методологию", "изучи глобальную папку", "как работает методология", "how does the methodology work", "explain the workflow" For infrastructure tasks, use infrastructure-setup or deploy-pipeline skills.

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 TeamCreate
• 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 — solution feasibility
• interview-completeness-checker — interview coverage gaps
• tech-spec-validator — template compliance
• skeptic — detects mirages (non-existent files/functions/APIs)
• completeness-validator — bidirectional requirements traceability, over/underengineering, solution depth
• task-validator — task template compliance
• task-creator — generates task files from tech-spec
• reality-checker — validates tasks against codebase

Reviewers (run during/after code writing)

• code-reviewer — code quality across 10 dimensions
• test-reviewer — test quality analysis with concrete fixes
• security-auditor — OWASP Top 10, auth, input validation
• prompt-reviewer — prompt quality against prompt-master principles
• documentation-reviewer — project-knowledge quality against documentation-writing principles
• deploy-reviewer — CI/CD pipeline and deployment configuration quality
• infrastructure-reviewer — folder structure, Docker, pre-commit hooks, .gitignore

Research

• code-researcher — codebase research for features (files, patterns, tests, integrations, risks)

QA

• pre-deploy-qa — pre-deploy acceptance testing (tests + acceptance criteria)
• post-deploy-qa — post-deploy verification on live environment (MCP tools, AVP)

Meta

• skill-checker — validates skills against skill-master standards

---

Commands Reference

Command	Purpose
/new-user-spec	Interview → user-spec.md
/new-tech-spec	Research → tech-spec.md
/decompose-tech-spec	Tech-spec → task files
/do-task	Execute single task with quality gates
/do-feature	Execute all tasks via agent teams
/done	Update PK, archive feature
/write-code	Ad-hoc coding with TDD and reviews
/init-project	Initialize new project with template, git, GitHub
/init-project-knowledge	Fill all project documentation via project-planning skill

---

Workflow Quick Start

New project: /init-project → /init-project-knowledge (interview + fill all docs) → start features

New feature: /new-user-spec → /new-tech-spec → /decompose-tech-spec → /do-feature or /do-task → /done

Ad-hoc coding (no spec): /write-code

To understand how a specific skill works internally, read its SKILL.md directly.