{
  "markdown": "# forge-skills\n\n> An Agentic Engineering toolkit for AI coding agents. The human writes specs and architecture. Agents implement in parallel with contracts. Review gates enforce correctness.\n\nStructured workflows that turn a raw idea into shipped, operated, and demoed code through 7 pipeline stages, 42 skills, and 13 specialist agent personas. Every discipline-enforcing skill is pressure-tested against fresh subagents using TDD-for-skills methodology (see [Testing](#testing)).\n\nAndrej Karpathy's Agentic Engineering concept (Feb 2026) describes exactly this model: humans write the specs, architecture, and guardrails — AI agents implement in parallel — humans review. The `.forge/` artifact chain is the implementation: `prd.md` → `architecture.md` + `contracts/` → `tasks.yaml` → code.\n\n---\n\n## Your AI Engineering Team\n\nThirteen specialist agents, available via the Task tool:\n\n| Agent | Role |\n|-------|------|\n| **Architect** | System design, interface contracts, ADRs |\n| **Platform Architect** | Multi-product boundaries, shared vs forked decisions, deploy topology |\n| **Project Manager** | Task breakdown, dependency ordering, scope management |\n| **Test Engineer** | TDD coaching, test quality review, coverage gaps |\n| **Code Reviewer** | PR review, contract validation, five-axis quality check |\n| **Security Auditor** | Threat modeling, OWASP prevention, hardening |\n| **Competitive Analyst** | Market research, feature matrices, positioning |\n| **Compliance Officer** | Regulatory assessment, data governance, certification |\n| **Reliability Engineer** | Errors, observability, incidents, performance — the person who gets paged |\n| **Data Engineer** | Schema, migrations, query performance, data integrity |\n| **QA Engineer** | Test strategy, quality gates — the person who breaks things before users do |\n| **Design Engineer** | Design system, interaction patterns, accessibility, visual quality |\n| **Brand Strategist** | Brand identity, voice and tone, cross-product consistency |\n\nEach agent has a defined role, push-back behavior, and quality bar. See `agents/` for the full personas.\n\n---\n\n## The Forge Pipeline\n\n```\n GRILL       SPEC       DESIGN       PLAN        BUILD      REVIEW      SHIP\n┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐\n│ Idea   │─▶│ PRD    │─▶│ Arch + │─▶│ Tasks  │─▶│ Code + │─▶│ 5-axis │─▶│ Launch │\n│ Brief  │  │        │  │Contract│  │  .yaml │  │  TDD   │  │ Review │  │  Gate  │\n└────────┘  └────────┘  └────────┘  └────────┘  └────────┘  └────────┘  └────────┘\n/grill      /spec      /architect    /plan       /build     /review      /ship\n```\n\n> **Install:** `/plugin marketplace add aneja5/forge-skills` then `/plugin install forge-skills@forge-skills`\n>\n> **New here?** Read [docs/HOW-TO-USE.md](docs/HOW-TO-USE.md) — a 10-minute walkthrough with copy-paste prompts for every skill.\n>\n> **Need patterns and a setup guide?** Read [docs/cookbook.md](docs/cookbook.md) — `Setup: Adding Forge to Your Project` plus situational patterns (greenfield, mid-project, brownfield, parallel, demo prep, incident).\n\n---\n\n## Commands, Skills, and Artifacts\n\n| Command | Phase | Skill | Reads | Produces |\n|---------|-------|-------|-------|----------|\n| `/grill` | Define | `idea-griller` | — | `.forge/idea-brief.md` |\n| `/spec` | Specify | `spec-driven-development` | `idea-brief.md` | `.forge/prd.md` |\n| `/architect` | Design | `architecture-and-contracts` | `prd.md` | `architecture.md` + `contracts/` + `adr/` |\n| `/plan` | Plan | `planning-and-task-breakdown` | `prd.md` + `architecture.md` + `contracts/` | `.forge/tasks.yaml` |\n| `/build` | Build | `incremental-implementation` + `tdd` | `tasks.yaml` + `contracts/` | code + commits |\n| `/review` | Review | `code-review-and-quality` | code + `contracts/` | findings + decision |\n| `/ship` | Ship | `shipping-and-launch` | ready code | go/no-go + rollback plan |\n| `/compete` | Analyze | `competitive-analysis` | `prd.md` | `.forge/competitive.md` |\n| `/gtm` | Analyze | `gtm-strategy` | `prd.md` + `competitive.md` | `.forge/gtm.md` |\n| `/secure` | Analyze | `security-and-compliance` | `architecture.md` | `.forge/security.md` |\n| `/scale` | Analyze | `scalability-analysis` | `architecture.md` | `.forge/scalability.md` |\n| `/validate` | Validate | `cross-validation` | `.forge/` artifacts | `.forge/cross-validation-*.md` |\n| `/redact` | Share | `redaction-and-cleanup` | `.forge/` artifacts | `.forge/redacted/` |\n| `/api` | Design | `api-design` | `prd.md` | `.forge/api-design.md` |\n| `/db` | Design | `database-design` | `prd.md` + `architecture.md` | `.forge/database-design.md` + `migrations-policy.md` |\n| `/brand` | Design | `brand-and-identity` | — | `.forge/brand-identity.md` |\n| `/design` | Design | `design-system` | `brand-identity.md` (soft) | `.forge/design-system.md` |\n| `/interaction` | Design | `interaction-patterns` | `design-system.md` | `.forge/interaction-patterns.md` |\n| `/components` | Design | `component-library` | `design-system.md` + `interaction-patterns.md` + `brand-identity.md` | `.forge/component-library.md` |\n| `/pages` | Design | `page-composition` | `component-library.md` + `design-system.md` + `interaction-patterns.md` | `.forge/page-composition.md` |\n| `/dataviz` | Design | `data-visualization` | `design-system.md` + `component-library.md` | `.forge/data-visualization.md` |\n| `/parallel` | Plan | `parallel-execution-strategy` | `tasks.yaml` | `.forge/parallel-plan.md` |\n| `/seed` | Plan | `seed-data-and-fixtures` | `architecture.md` + `database-design.md` | `.forge/seed-data.md` |\n| `/test-strategy` | Plan | `testing-strategy` | `prd.md` | `.forge/testing-strategy.md` |\n| `/errors` | Operate | `error-handling-and-resilience` | `architecture.md` | `.forge/error-handling.md` |\n| `/observe` | Operate | `observability` | `architecture.md` | `.forge/observability.md` |\n| `/perf` | Operate | `performance-and-cost-optimization` | `architecture.md` | `.forge/performance-budget.md` |\n| `/incident` | Operate | `incident-response-and-postmortems` | live incident or service inventory | `.forge/incident-response.md` |\n| `/a11y` | Polish | `accessibility` | UI surfaces | `.forge/accessibility.md` |\n| `/polish` | Polish | `visual-polish` | all UI artifacts | `.forge/polish-checklist.md` |\n| `/debt` | Polish | `refactoring-and-tech-debt` | codebase | `.forge/tech-debt-registry.md` |\n| `/demo` | Polish | `demo-narrative` | `prd.md` + `seed-data.md` | `.forge/demo-narrative.md` |\n| `/docs` | Polish | `documentation-hygiene` | repo | `.forge/docs-policy.md` |\n| `/sync` | Cross-cutting | `forge-sync` | every `.forge/` file + dependency graph | `.forge/sync-report.md` |\n| `/forge-migrate` | Cross-cutting | `forge-migrate` | legacy `.forge/` files lacking headers | in-place `forge:meta` backfill |\n| `/feedback` | Cross-cutting | `feedback` | one upstream artifact + a downstream finding | `.forge/feedback/<ts>-<source>.md` |\n| — | Verify | `debugging-and-recovery` | bug report | fix + regression test |\n| — | Ship | `git-workflow` | completed tasks | atomic commits + PR |\n| — | Triage | `triage-issue` | bug report | GitHub issue + TDD plan |\n| — | Meta | `writing-skills` | new skill spec | tested skill + scenarios + results |\n\nAdd `.forge/` to `.gitignore` for local-only, or commit it to share context across the team.\n\n> **See [examples](docs/examples.md)** for before/after diffs of each pipeline stage.\n\n---\n\n<details>\n<summary><b>Quick Start — Claude Code</b></summary>\n\n**Marketplace install (recommended):**\n\n```\n/plugin marketplace add aneja5/forge-skills\n/plugin install forge-skills@forge-skills\n```\n\n**Install one skill:**\n\n```bash\ncurl -sL https://raw.githubusercontent.com/aneja5/forge-skills/main/install.sh | bash -s idea-griller\n```\n\n**Manual clone:**\n\n```bash\ngit clone https://github.com/aneja5/forge-skills.git\ncp -r forge-skills/skills ~/.claude/skills\ncp -r forge-skills/agents ~/.claude/agents\ncp -r forge-skills/commands ~/.claude/commands\n```\n\n**Enable the session-start hook** (optional — injects the pipeline at every session start):\n\nCopy `hooks/hooks.json` content into your project's `.claude/settings.json`.\n\n**Start using:**\n\n```\n/grill    ← describe your idea\n/spec     ← formalize requirements\n/architect ← design the system\n/plan     ← break into tasks\n/build    ← implement (TDD)\n/review   ← validate against contracts\n/ship     ← pre-launch gate\n```\n\n</details>\n\n<details>\n<summary><b>Quick Start — Cursor / Gemini CLI / Other</b></summary>\n\n**Cursor** — add to `.cursorrules`:\n\n```bash\ncat skills/using-forge-skills/SKILL.md > .cursorrules\n```\n\n**Gemini CLI:**\n\n```bash\ngemini skills install ./forge-skills/skills/\n```\n\nSee [docs/cursor-setup.md](docs/cursor-setup.md) for Cursor, Gemini CLI, Windsurf, and other tools.\n\n</details>\n\n---\n\n<details>\n<summary><b>Agent Personas & Reference Checklists</b></summary>\n\n### Agent Personas\n\n| Persona | File | When to invoke |\n|---------|------|----------------|\n| Architect | `agents/architect.md` | System design, contracts, tech decisions |\n| Platform Architect | `agents/platform-architect.md` | Multi-product boundaries, shared vs forked, deploy topology |\n| Project Manager | `agents/project-manager.md` | Task breakdown, dependency mapping |\n| Test Engineer | `agents/test-engineer.md` | TDD coaching, test quality review |\n| Code Reviewer | `agents/code-reviewer.md` | PR review, contract compliance |\n| Security Auditor | `agents/security-auditor.md` | Threat modeling, OWASP review |\n| Competitive Analyst | `agents/competitive-analyst.md` | Market research, positioning |\n| Compliance Officer | `agents/compliance-officer.md` | Regulatory assessment, certification |\n| Reliability Engineer | `agents/reliability-engineer.md` | Errors, observability, incidents, performance |\n| Data Engineer | `agents/data-engineer.md` | Schema, migrations, query performance |\n| QA Engineer | `agents/qa-engineer.md` | Test strategy, quality gates |\n| Design Engineer | `agents/design-engineer.md` | Visual system, interaction, accessibility |\n| Brand Strategist | `agents/brand-strategist.md` | Brand identity, voice and tone, cross-product consistency |\n\n### Reference Checklists\n\n| File | Used by |\n|------|---------|\n| `references/contract-templates.md` | architecture-and-contracts |\n| `references/idea-evaluation.md` | idea-griller |\n| `references/testing-patterns.md` | tdd, incremental-implementation, code-review-and-quality |\n| `references/security-checklist.md` | shipping-and-launch, security-auditor |\n\n</details>\n\n<details>\n<summary><b>Project Structure</b></summary>\n\n```\nforge-skills/\n├── skills/                          # All skill definitions\n│   ├── using-forge-skills/          # Meta-skill\n│   ├── idea-griller/                # + evaluation-criteria.md\n│   ├── spec-driven-development/\n│   ├── architecture-and-contracts/\n│   ├── planning-and-task-breakdown/\n│   ├── incremental-implementation/\n│   ├── tdd/                         # + deep-modules.md, mocking.md, tests.md, ...\n│   ├── debugging-and-recovery/\n│   ├── code-review-and-quality/\n│   ├── git-workflow/\n│   ├── shipping-and-launch/\n│   ├── triage-issue/\n│   ├── competitive-analysis/\n│   ├── gtm-strategy/\n│   ├── security-and-compliance/\n│   ├── scalability-analysis/\n│   ├── cross-validation/\n│   ├── redaction-and-cleanup/\n│   ├── api-design/\n│   ├── database-design/\n│   ├── brand-and-identity/          # Brand foundations, voice, logo, icons\n│   ├── design-system/\n│   ├── interaction-patterns/\n│   ├── component-library/           # Component catalog with props, states, accessibility\n│   ├── page-composition/            # Page templates + responsive collapse strategy\n│   ├── data-visualization/          # Chart selection rules + color encoding\n│   ├── visual-polish/               # Quality pass before demo/ship\n│   ├── parallel-execution-strategy/\n│   ├── seed-data-and-fixtures/\n│   ├── testing-strategy/\n│   ├── error-handling-and-resilience/\n│   ├── observability/\n│   ├── performance-and-cost-optimization/\n│   ├── incident-response-and-postmortems/\n│   ├── accessibility/\n│   ├── refactoring-and-tech-debt/\n│   ├── demo-narrative/\n│   ├── documentation-hygiene/\n│   ├── writing-skills/              # Meta-skill for contributors\n│   ├── forge-sync/                  # Check .forge/ artifact freshness\n│   ├── forge-migrate/               # Backfill forge:meta headers on legacy .forge/ files\n│   └── feedback/                    # Reverse-cascade entries (downstream → upstream)\n├── agents/                          # Specialist agent personas\n│   ├── architect.md\n│   ├── project-manager.md\n│   ├── test-engineer.md\n│   ├── code-reviewer.md\n│   ├── security-auditor.md\n│   ├── competitive-analyst.md\n│   ├── compliance-officer.md\n│   ├── reliability-engineer.md\n│   ├── data-engineer.md\n│   ├── qa-engineer.md\n│   ├── design-engineer.md\n│   ├── brand-strategist.md          # Brand identity, voice, cross-product consistency\n│   └── platform-architect.md        # Multi-product boundaries, shared vs forked\n├── references/                      # Shared checklists and templates\n│   ├── contract-templates.md\n│   ├── idea-evaluation.md\n│   ├── testing-patterns.md\n│   ├── security-checklist.md\n│   ├── motion-system.md             # Durations, curves, transitions, reduced-motion\n│   └── forge-dependency-graph.md    # Canonical .forge/ dependency tree\n├── commands/                        # 36 slash commands across the full lifecycle\n├── hooks/\n│   ├── hooks.json\n│   └── session-start.sh\n├── .claude-plugin/\n│   ├── plugin.json                  # Plugin manifest\n│   └── marketplace.json             # Marketplace listing\n├── tests/                           # Pressure scenarios + RED/GREEN results\n│   ├── METHODOLOGY.md\n│   ├── idea-griller/\n│   ├── architecture-and-contracts/\n│   └── spec-driven-development/\n├── docs/\n│   ├── getting-started.md\n│   ├── skill-anatomy.md\n│   ├── cursor-setup.md\n│   ├── the-forge-pipeline.md\n│   ├── examples.md\n│   └── HOW-TO-USE.md\n├── install.sh\n├── LICENSE\n├── CLAUDE.md\n└── AGENTS.md\n```\n\n</details>\n\n---\n\n## Testing\n\nSkills are pressure-tested against fresh subagents using **TDD-for-skills** methodology adapted from [Superpowers' writing-skills](https://github.com/obra/superpowers/tree/main/skills/writing-skills):\n\n- **RED** — run a pressure scenario on a fresh subagent without the skill. Document verbatim failures and rationalizations.\n- **GREEN** — run the same scenario with the skill loaded. Verify compliance and cited sections.\n- **REFACTOR** — close any new rationalizations the agent invented.\n\nTest results live in `tests/<skill>/results.md`. See [tests/METHODOLOGY.md](tests/METHODOLOGY.md) for the full cycle and the [writing-skills](skills/writing-skills/SKILL.md) skill for contributors.\n\n**Iron Law:** *No skill ships without a failing test first.*\n\n### Quick integrity check without Claude Code\n\n`./bin/forge-check.sh` is a standalone bash script (macOS-friendly, uses `shasum`) that scans every `.forge/` artifact and verifies two things:\n\n1. Each file's `content_hash` matches its body's actual sha256 (catches manual edits → **MODIFIED**)\n2. Each `generated_from` snapshot still matches the upstream's current `content_hash` (catches upstream drift → **STALE**)\n\n```bash\n./bin/forge-check.sh             # checks ./.forge\n./bin/forge-check.sh path/to/.forge\n\n# Exit codes: 0 clean | 1 modified | 2 stale\n```\n\nUseful in CI, pre-commit hooks, or when sanity-checking a repo on a machine without Claude Code installed.\n\n---\n\n## Contributing\n\n1. Read `skills/writing-skills/SKILL.md` — it encodes the contribution flow\n2. Create `tests/<name>/scenarios.md` first (3+ pressure scenarios)\n3. Run RED — record verbatim subagent failures in `tests/<name>/results.md`\n4. Write `skills/<name>/SKILL.md` (under 150 lines, CSO-compliant description, follow [docs/skill-anatomy.md](docs/skill-anatomy.md))\n5. Run GREEN — verify the skill closes the failures\n6. REFACTOR until no new rationalizations appear\n7. Add slash command in `commands/` if it fits the pipeline\n8. Update the skills table, `using-forge-skills` discovery flowchart, `install.sh`, and CLAUDE.md\n\n---\n\n## Credits & Inspiration\n\n**Andrej Karpathy** — Behavioral principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) and the Agentic Engineering concept (Feb 2026) that frames the human-as-architect, AI-as-implementer model the forge pipeline embodies.\n\n**Addy Osmani** ([agent-skills](https://github.com/addyosmani/agent-skills)) — Skill anatomy standard: frontmatter, When to Use / When NOT to Use, Common Rationalizations, Red Flags, Verification checklists. The anti-rationalization pattern is directly from his work.\n",
  "bytes": 16667,
  "sha": "2e0ce583e898fee0ab5ee2c10e952fe42b841b35a0dbd3de76cb80ec4103c12e",
  "repo_slug": "aneja5/forge-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_aneja5_forge_skills_forge_skills_25087d84/readme"
}