{
  "markdown": "# Project Scaffolder — Fable Edition\n\n**Skills that learn, connect, and grow — like neurons in a living project.**\n\nGenerate a complete project knowledge base from a single brief, then orchestrate development with an AI project leader, quality pipeline, and skills that compound expertise over time. One brief in, entire project structure out — then every task makes the system smarter.\n\n---\n\n## The Problem\n\nEvery new software project starts from zero. Without structured context, AI coding agents:\n\n- **Waste 60-70% of tokens** re-explaining the project each session\n- **Repeat solved errors** because nobody documented them\n- **Produce inconsistent code** across sessions (different patterns, naming, architecture)\n- **Suffer context rot** — quality degrades in long conversations as the agent loses track of earlier decisions\n\nThe cost compounds: decisions made and forgotten get remade differently, bugs resurface, and the codebase diverges from its original vision.\n\n## The Solution\n\nProject Scaffolder creates a **persistent knowledge layer** that survives between sessions. It combines three proven patterns:\n\n| Pattern | Inspiration | What It Does |\n|---------|-------------|-------------|\n| **Persistent Markdown wiki** | [Andrej Karpathy's gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) | Durable project memory: decisions, architecture, errors, priorities. Read automatically every session. |\n| **Vertical skills** | Claude Code skills system | Specialized guides per area (frontend, domain logic, marketing, release). Contain reusable code patterns, rules, checklists. |\n| **Structured handoff** | Original pattern | Session transition protocol that prevents context rot. One phase per chat, wiki as persistent memory. |\n| **Karpathy Coding Discipline** | [Karpathy's LLM coding pitfalls](https://github.com/forrestchang/andrej-karpathy-skills) | Behavioral guardrails injected into every generated skill and CLAUDE.md: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution. |\n\n**Result:** The AI agent restarts every session with complete context in seconds, without wasting tokens.\n\n## What's New in v3.0 — Fable Edition\n\n**v3.0 Fable Edition:** phase Execution Docs with model routing, proactive context handoff, wiki lifecycle with archive, destructive-command guardrail hooks, auto-format hook. v1.x solves the cold-start problem (scaffolding). v2.0 introduced the development lifecycle (Cortex + Synapse + Persona-Lab). v2.1 adds the `pipeline-logger` skill for full audit trail and analytics. See [CHANGELOG.md](CHANGELOG.md) for details.\n\n| Component | What it does |\n|-----------|-------------|\n| **Cortex** (`/task`) | AI project leader — classifies tasks, delegates to specialists, runs QA and user testing, manages the feedback loop |\n| **Synapse** | Nervous system — propagates learning between connected skills, maintains connection map, prevents repeated errors |\n| **Persona-Lab** | Simulated focus group — tests features with diverse user profiles, catches UX issues before release |\n| **QA Agent** | Ephemeral code reviewer — Karpathy compliance, test verification, surgical change validation |\n| **Skill Lifecycle** | Skills grow from Seed → Growing → Mature → Expert as they accumulate real-world experience |\n| **On-demand Skills** | Cortex generates new skills mid-session when a task requires uncovered expertise |\n\n### The Development Pipeline\n\n```\n/task \"Implement feature X\"\n    │\n    ▼\nCORTEX ── classify ── skill lookup/generate ── delegate to specialist\n    │                                              │\n    │                                    ┌─────────┘\n    │                                    ▼\n    │                              QA AGENT (verify)\n    │                                    │\n    │                              PERSONA-LAB (test)\n    │                                    │\n    │                              SYNAPSE (learn + propagate)\n    │                                    │\n    └◀──────────── task complete ────────┘\n```\n\n## What It Generates\n\nFrom a single brief like:\n\n> \"Mobile app for tracking digital subscriptions. Target: users who lose track of recurring charges. Flutter.\"\n\nThe scaffolder produces:\n\n### 1. CLAUDE.md — Central Hub\nThe project's single source of truth. Read automatically by Claude Code at every session start. Contains navigation to all files, skill references, operative rules, and session management protocol.\n\n### 2. Wiki — 12 Core Pages + On-Demand\n\n12 core pages are always generated up front; everything else is created on-demand, the first time a task actually needs it, and listed in `wiki/index.md` under \"on-demand (not yet created)\".\n\n**Core (12, always generated):**\n\n| Section | Files | Purpose |\n|---------|-------|---------|\n| **Hub** | CLAUDE.md, wiki/index.md | Central hub + navigation map |\n| **Product** | overview, priorities, product/roadmap, product/decisions | What to build, in what order, why each choice was made |\n| **Technical** | architecture, tech-stack | How it's built: structure, tools, conventions |\n| **Debug** | debugging/known-errors | Error memory: what didn't work and why |\n| **Guardrails** | guardrails/errors-to-avoid | Hard-won lessons, anti-patterns |\n| **Operations** | log, handoff | Timeline, session transitions |\n\n**On-demand (created on first real use):**\n\n| Section | Files | Purpose |\n|---------|-------|---------|\n| **Identity** | vision, glossary | Why it exists, shared vocabulary |\n| **Product** | product/features | Feature-level detail |\n| **Technical** | scripts, workflows, prompts, setup-claude-code | Automations, session setup |\n| **Design** | branding, ux/ui-decisions | Visual identity, interface principles |\n| **Debug** | debugging/failed-experiments | What didn't work and why |\n| **Incubator** | incubator/raw-ideas, incubator/future-directions | Unvalidated ideas, long-term explorations |\n\n### 3. Vertical Skills — Domain-Specific Guides\n\nEach skill is a `SKILL.md` with YAML frontmatter, containing code patterns, rules, checklists, and anti-patterns specific to one area. Skills are auto-selected based on your tech stack and domain:\n\n**Always generated:**\n- `release-gate` — 5-stage pre-release verification orchestrator\n- `brand-voice` — Tone of voice, copy patterns, language rules\n- `product-strategy` — RICE scoring, competitor analysis, feature evaluation\n\n**By tech stack** (e.g., Flutter):\n- `flutter-patterns` — Themes, state management, folder structure, model conventions\n\n**By domain** (e.g., subscriptions):\n- `subscription-domain` — Renewal calculations, cost normalization, validation rules\n\n**By distribution** (e.g., Play Store):\n- `play-store-launch` — ASO, store listing, release management\n\n### 4. Guardrails\n`errors-to-avoid.md` — Cumulative record of errors, traps, and anti-patterns. Prevents repeating mistakes across sessions.\n\n### 5. Design Spec\nComplete project specification derived from brainstorming: architecture, data models, business model, roadmap, and skill ecosystem.\n\n### 6. Handoff Protocol\nStructured session transition system. Each session ends by updating `handoff.md` with what was done, what remains, blockers, and which files the next session should read. The next session picks up instantly.\n\n## Interaction Modes\n\nControl how much Claude asks during scaffolding AND all subsequent development sessions.\n\n| Mode | Questions | Best For |\n|------|-----------|----------|\n| **Normal** | All questions asked | First-time users, learning the methodology |\n| **Autopilot** | Only critical questions (~50% fewer) | Experienced users who trust reasonable defaults |\n| **Autonomous** | Zero questions (unless truly blocked) | Well-defined projects, maximum speed |\n\n```\n/scaffold --mode autopilot Mobile app for tracking expenses. Target: millennials. Flutter.\n```\n\nThe mode is written into the generated `CLAUDE.md`, so every future session respects your preference. All autonomous decisions are documented in `wiki/product/decisions.md` with full rationale — nothing is lost, you just aren't interrupted.\n\n**Recommended:** Autopilot for most users. Autonomous for experienced developers with clear project specs.\n\n## Token Optimization\n\nv3 token diet: 12-file core wiki, injection budgets, one report per task.\n\n## Karpathy Coding Discipline\n\nInspired by [Andrej Karpathy's observations](https://github.com/forrestchang/andrej-karpathy-skills) on LLM coding pitfalls, the scaffolder integrates behavioral guardrails at every level of the generated project:\n\n| Where | What's Added |\n|-------|-------------|\n| **CLAUDE.md template** | \"Coding Discipline\" section with 4 principles: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution |\n| **Phase 2 (Brainstorming)** | Mandatory \"Assumption Surfacing\" step — all inferences tagged `[HYPOTHESIS]` before proceeding |\n| **Design Spec** | Dedicated \"Assumptions\" section with confidence levels |\n| **priorities.md** | Every task requires verifiable success criteria (`→ VERIFY: ...`) |\n| **Technical skills** | \"Behavioral Rules\" section in every generated skill template |\n| **Release-gate** | Stage 6: Simplicity Check — scope creep, over-engineering, dead code, speculative features |\n| **Anti-patterns** | 3 new entries: no speculative features, no silent assumptions, no adjacent code changes |\n\n**Why this matters:** The original Karpathy plugin is a single generic file. Project Scaffolder makes those principles **contextual** — embedded in domain-specific skills, project-specific guardrails, and verifiable at release time.\n\n## How It Works\n\n```\nUser Brief\n    │\n    ▼\n┌─────────────────┐\n│  0. Mode         │  Select interaction mode (Normal/Autopilot/Autonomous)\n│  1. Analyze      │  Extract domain, tech stack, target, business model\n│  2. Brainstorm   │  Architecture, UX, business, technical decisions\n│  3. Design Spec  │  Complete project specification\n│  4. Structure    │  Create directories\n│  5. Wiki         │  2 parallel agents generate 12 core wiki pages\n│  6. Skills       │  Generate domain-specific vertical skills\n│  7. Verify       │  All files exist, all links resolve\n│  8. Handoff      │  Ready for Phase 1 development\n└─────────────────┘\n    │\n    ▼\n\"claude\" → \"Proceed with Phase 1\"\n```\n\n**Time:** 15 minutes (simple project) to 40 minutes (complex platform).\n\n## Installation\n\n### From GitHub\n\n```bash\nclaude plugin add valsecchi75/project-scaffolder\n```\n\n### From local directory\n\n```bash\nclaude plugin add /path/to/project-scaffolder\n```\n\n## Usage\n\n### Option 1: Slash Command\n\n```\n/scaffold Mobile app for tracking gym workouts. Target: fitness enthusiasts. Flutter + Dart.\n```\n\n### Option 2: With Mode Flag\n\n```\n/scaffold --mode autopilot SaaS platform for restaurant reservations. React + Node. Target: Italian restaurant owners.\n```\n\n### Option 3: Natural Language\n\n```\nNew project: E-commerce site for handmade jewelry. My customers are women 25-45 who value artisan quality.\n```\n\nThe skill detects that you're starting a new project and activates automatically. If no mode is specified, you'll be asked to choose.\n\n## Slash Commands Reference\n\nThe plugin ships 19 slash commands grouped by workflow phase. Each command is focused, predictable, and safe to rerun.\n\n### Project lifecycle\n\n| Command | Purpose | Writes files? |\n|---------|---------|---------------|\n| `/scaffold` | Generate a complete project knowledge base from a brief | Yes — creates CLAUDE.md, wiki, skills, guardrails |\n| `/phase-doc` | Generate the phase Execution Doc — hard gate for `/task` | Yes |\n| `/task` | Assign work to the Cortex pipeline (classify → execute → QA → test → learn) | Yes — source code + logs |\n\n### Session lifecycle\n\n| Command | Purpose | Writes files? |\n|---------|---------|---------------|\n| `/kickoff` | Start-of-session briefing: reads CLAUDE.md, handoff, priorities, guardrails, synapse map | No |\n| `/wrap` | End-of-session ritual: updates handoff, priorities, daily log; optional `--commit` | Yes |\n| `/phase-shift <N>` | Formal transition between phases; archives current phase, opens the next | Yes |\n\n### Development\n\n| Command | Purpose | Writes files? |\n|---------|---------|---------------|\n| `/plan <task>` | Write an implementation plan with verifiable steps — before any code | Yes — plan file |\n| `/implement <plan>` | Execute a plan through Cortex, step-by-step with QA on each | Yes — source code |\n| `/review [scope]` | Code review on a diff using Karpathy checklist (SCOPE, SIMPLICITY, SURGICAL, DEAD CODE) | No |\n| `/debug <symptom>` | Systematic debugging: reproduce → isolate → diagnose → fix → document | Yes — known-errors, guardrails |\n| `/test [scope]` | Run tests with consistent reporting; scopes: `--changed`, `--all`, `--coverage`, `--file` | No (logs only) |\n\n### Release and quality\n\n| Command | Purpose | Writes files? |\n|---------|---------|---------------|\n| `/gate` | Run the 6-stage release-gate skill (includes Simplicity Check); fail-fast | No (logs only) |\n| `/ship [--patch\\|--minor\\|--major]` | Full release pipeline: gate + version bump + changelog + tag. Never pushes automatically | Yes |\n\n### Knowledge management\n\n| Command | Purpose | Writes files? |\n|---------|---------|---------------|\n| `/decide <title>` | Document a decision with alternatives and rationale; auto-increments DEC-NNN | Yes — decisions.md |\n| `/error <title>` | Log a bug atomically across known-errors, guardrails, and propagate via Synapse | Yes |\n| `/wiki-gc` | Archive stale wiki content, enforce line caps | Yes |\n\n### Skills and analytics\n\n| Command | Purpose | Writes files? |\n|---------|---------|---------------|\n| `/skills [--status]` | Show the skill map with maturity, connections, pending propagations | No |\n| `/forge <domain>` | Create a new vertical skill on-demand for a specific domain | Yes — skills/ |\n| `/stats [timeframe]` | Pipeline metrics from logs: volume, quality, rejection reasons, skill usage | No |\n\n### Typical daily flow\n\n```\n/kickoff                             # See where you are\n/phase-doc                           # Mandatory at the start of a phase — the Cortex gate refuses /task and /implement without it\n/plan Add monthly-spend widget       # Think first\n/implement @latest                   # Execute the plan through Cortex\n/review                              # Sanity-check the diff\n/decide Widget refresh = 15 min      # Record the decision\n/wrap --commit                       # Close the session cleanly\n```\n\n## After Scaffolding: The Daily Workflow\n\n```\n1. Open terminal\n2. cd into project folder\n3. claude\n4. \"Proceed with [what you need to do]\"\n5. Work...\n6. \"Update handoff and daily log\"\n7. /exit\n```\n\nThe wiki maintains memory between sessions. Every time you reopen Claude Code, it knows exactly where you left off.\n\n## Session Management: One Phase Per Chat\n\nA key innovation of this methodology: **each development phase runs in its own chat session**.\n\n**Why:** Long conversations degrade AI response quality (context rot). After thousands of tokens, the agent forgets earlier decisions, repeats mistakes, and produces declining-quality output.\n\n**How:** At the end of each session, the agent updates `handoff.md`, `priorities.md`, and the daily log. The next session reads `CLAUDE.md` → `handoff.md` and starts fresh with complete context.\n\n**Result:** Every session is as sharp as the first one.\n\n## Measured Benefits\n\n| Benefit | Without methodology | With methodology |\n|---------|-------------------|-----------------|\n| Project setup | 2-4 hours manual | 15-40 min automated |\n| Tokens per session | 100% (baseline) | 30-40% (60-70% savings) |\n| Code consistency | Degrades over time | Stable (skills as guardrails) |\n| New session onboarding | 5-10 min of context | Automatic (CLAUDE.md + handoff) |\n| Repeated errors | Frequent | Rare (documented guardrails) |\n| Decision tracking | Lost in chat | Permanent in wiki |\n| Parallelism | Sequential | Parallel subagents (2 wiki agents) |\n\n## Supported Project Types\n\n| Type | Example Skills Generated |\n|------|------------------------|\n| **Mobile app (Flutter)** | flutter-patterns, [domain]-domain, brand-voice, growth-marketing, play-store-launch, release-gate |\n| **Mobile app (React Native)** | react-native-patterns, [domain]-domain, brand-voice, app-store-launch, release-gate |\n| **Web app (React/Next.js)** | react-patterns, [domain]-domain, brand-voice, seo-strategy, deploy-pipeline, release-gate |\n| **API / Backend** | api-patterns, [domain]-domain, database-schema, auth-security, deploy-pipeline, release-gate |\n| **E-commerce** | frontend-patterns, product-catalog, payment-flow, brand-voice, seo-strategy, release-gate |\n| **SaaS** | frontend-patterns, [domain]-domain, pricing-strategy, onboarding-flow, growth-marketing, release-gate |\n\n## Real-World Results (v2.x baseline)\n\nTested on a production mobile app project (Android, Flutter, freemium model):\n\n| Metric | Value |\n|--------|-------|\n| Files generated (Phase 0) | 33 |\n| Wiki pages | 21 |\n| Vertical skills | 8 |\n| Documented decisions | 7 |\n| Catalogued errors | 1 |\n| Phase 0 time | ~1 session |\n| Estimated token savings | 60-70% in subsequent sessions |\n\n## Project Structure\n\n```\nproject-scaffolder/\n├── .claude-plugin/\n│   ├── plugin.json              # Plugin metadata (v3.0.0)\n│   └── marketplace.json         # Marketplace entry\n├── commands/\n│   ├── scaffold.md              # /scaffold — generate project structure\n│   ├── phase-doc.md             # /phase-doc — generate phase Execution Doc\n│   ├── task.md                  # /task — assign work to Cortex\n│   ├── kickoff.md               # /kickoff — start-of-session ritual\n│   ├── wrap.md                  # /wrap — end-of-session ritual\n│   ├── phase-shift.md           # /phase-shift — transition phases\n│   ├── plan.md                  # /plan — write plan before coding\n│   ├── implement.md             # /implement — execute a plan\n│   ├── review.md                # /review — code review on diff\n│   ├── debug.md                 # /debug — systematic debugging\n│   ├── test.md                  # /test — run tests with report\n│   ├── gate.md                  # /gate — release-gate verification\n│   ├── ship.md                  # /ship — full release pipeline\n│   ├── decide.md                # /decide — document decision\n│   ├── error.md                 # /error — log bug atomically\n│   ├── wiki-gc.md               # /wiki-gc — wiki archive & line-cap enforcement\n│   ├── skills.md                # /skills — show skill map\n│   ├── forge.md                 # /forge — create skill on-demand\n│   └── stats.md                 # /stats — pipeline metrics\n├── skills/\n│   ├── project-scaffolder/SKILL.md   # Phase 0 scaffolding\n│   ├── cortex/SKILL.md               # Project Leader orchestration\n│   ├── synapse/SKILL.md              # Learning propagation engine\n│   ├── persona-lab/SKILL.md          # End-user simulation\n│   ├── context-manager/SKILL.md      # Proactive context handoff (v3)\n│   └── pipeline-logger/SKILL.md      # Audit trail & analytics\n├── hooks/\n│   ├── deny-dangerous.sh             # PreToolUse guard (bash)\n│   ├── deny-dangerous.ps1            # PreToolUse guard (PowerShell variant)\n│   ├── dangerous-patterns.txt        # Case-insensitive destructive-command patterns\n│   ├── dangerous-patterns-case-sensitive.txt  # Case-sensitive patterns (e.g. git branch -D)\n│   ├── auto-format.sh                # PostToolUse formatter\n│   └── hooks.json                    # Hook wiring (PreToolUse + PostToolUse)\n├── templates/\n│   └── execution-doc.md              # Template for docs/phases/PHASE-{N}-execution.md\n├── CHANGELOG.md\n├── LICENSE\n└── README.md\n```\n\n## Contributing\n\nFound a domain or tech stack that's not covered? Want to improve a template?\n\n1. Fork this repository\n2. Add your domain/stack templates to the skill file\n3. Test on a real project\n4. Submit a pull request\n\n## Credits\n\n- **Methodology:** Developed by [agent1.it](https://agent1.it)\n- **Knowledge pattern:** Inspired by [Andrej Karpathy's Markdown wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)\n- **Built with:** [Claude Code](https://claude.com/product/claude-code) by Anthropic\n- **Skills system:** [Claude Code plugins](https://claude.com/plugins)\n\n## License\n\nMIT License — use it, fork it, improve it.\n",
  "bytes": 20293,
  "sha": "854823f5fe37cf1f3db8ab7123efbdaae8ae06c621ea3853c7beda68c37c5a46",
  "repo_slug": "valsecchi75/project-scaffolder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_valsecchi75_project_scaffolder_project_s_a862246f/readme"
}