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