git:20260930.3dd2ad1 to git:20261010.692f647

- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

-

- ## What This Is

-

- **The Agentic Startup** is a spec-driven development framework for Claude Code, distributed as marketplace plugins. It provides workflow commands, autonomous skills, specialized agents, and output styles to transform how you build software.

-

- ## Repository Structure

-

- ```

- the-startup/

- ├── plugins/

- │ ├── start/ # Core workflow orchestration plugin

- │ │ ├── .claude-plugin/ # Plugin manifest (plugin.json)

- │ │ ├── skills/ # workflow skills (user-invocable) + internal spec/implement skills

- │ │ ├── output-styles/ # The Startup, The ScaleUp output styles

- │ │ └── README.md # Detailed plugin documentation

- │ │

- │ ├── team/ # Specialized agent library plugin

- │ │ ├── agents/ # 8 roles with 15 consolidated activity agents

- │ │ │ ├── the-chief.md # Complexity assessment, routing

- │ │ │ ├── the-analyst/ # research-product

- │ │ │ ├── the-architect/ # design-system, review-security, review-robustness, review-compatibility

- │ │ │ ├── the-developer/ # build-feature, optimize-performance, etc.

- │ │ │ ├── the-devops/ # build-platform, monitor-production

- │ │ │ ├── the-designer/ # research-user, design-interaction, design-visual

- │ │ │ ├── the-tester/ # test-strategy

- │ │ │ └── the-meta-agent.md # Agent design and generation

- │ │ └── skills/ # 16 consolidated cross-cutting and domain skills

- │ │

- │ └── constitution/ # Project governance rules plugin (optional)

- │

- ├── scripts/

- │ ├── statusline.sh # Custom statusline for Claude Code terminal

- │ └── statusline.toml # Statusline configuration template

- │

- ├── docs/

- │ ├── PHILOSOPHY.md # Activity-based architecture rationale

- │ ├── PRINCIPLES.md # Core development principles

- │ ├── patterns/ # Technical patterns documentation

- │ └── specs/ # Feature specifications (requirements, solution, plan + scenarios)

- │

- ├── package.json # npm package definition for npx installer

- └── README.md # User-facing documentation

- ```

- ## Key Concepts

- ### Plugin Architecture

- Each plugin lives in `plugins/[name]/` with:

- - `.claude-plugin/plugin.json` - Plugin manifest defining name, version, components

- - `commands/` - Slash command definitions (markdown files)

- - `skills/` - Autonomous skills (SKILL.md files with trigger terms)

- - `output-styles/` - Output style definitions

- - `agents/` - Agent definitions (team plugin only)

- ### Skill Structure

- Skills use progressive disclosure to minimize context usage:

- skills/[skill-name]/

- ├── SKILL.md # Core logic (~7-24 KB, always loaded)

- ├── reference/ # Advanced protocols (loaded when needed)

- ├── templates/ # Document templates

- ├── examples/ # Real-world scenarios

- └── validation.md # Quality checklists

- For full skill conventions, PICS structure, and transformation checklist, see the `writing-skills` skill (`plugins/start/skills/writing-skills/reference/conventions.md`).

-

- ### Agent Structure (Team Plugin)

-

- Agents are organized by role with activity-based specializations:

- ```

- agents/the-[role]/

- ├── [activity-1].md # e.g., the-architect/design-system.md

- ├── [activity-2].md # e.g., the-architect/review-security.md

- └── ...

- ```

- Each agent markdown file defines:

- - Purpose and trigger conditions

- - Tool access permissions

- - Activation examples

- - Integration with other agents

- ## Development Workflow

- ### Testing Changes Locally

- # The plugins are directories - test by installing from local path

- claude plugin install ./plugins/team

-

- # Or use the interactive installer to test full installation

- npx the-startup

-

- # Uninstall to reset

- claude plugin uninstall team@the-startup

- ### Editing Skills

-

- 1. Skills are markdown files (`SKILL.md`) - edit directly

- 2. Skills activate on trigger terms defined in their YAML frontmatter

- 3. Keep `SKILL.md` under ~25 KB for context efficiency

- 4. Move advanced content to `reference/` directory (loaded on demand)

-

- ### Editing Commands

-

- 1. Commands are markdown files in `plugins/[plugin]/commands/`

- 2. Command name matches filename (e.g., `specify.md` → `/start:specify`)

- 3. Commands orchestrate skills - they define workflow, skills provide implementation

-

- ### Editing Agents

-

- 1. Agents are markdown files in `plugins/team/agents/[role]/`

- 2. Agent name matches `[role]:[activity]` pattern

- 3. Agents define specialized Task tool prompts for subagent delegation

-

- ### Editing Output Styles

-

- 1. Output styles are markdown files in `plugins/[plugin]/output-styles/`

- 2. Define personality, voice, and behavioral patterns

- 3. Activated via `/output-style [plugin]:[style-name]`

-

- ## Important Patterns

-

- ### Progressive Disclosure

-

- Skills load minimal context initially, then progressively load:

- - `reference/` - Advanced protocols when complexity increases

- - `templates/` - Document templates when creating artifacts

- - `examples/` - Real-world scenarios when pattern matching

-

- ### Spec-Driven Development

-

- The primary workflow: `/start:specify` → `/start:validate` → `/start:implement` → `/start:review`

-

- The specification describes **WHY** and **WHAT** (the target state and what "done" looks like); the implementation is a set of **tasks** in the spec's tracker. **HOW** to build each task is decided by the code agent inside the implementation loop. The two concerns are split across a clean line.

-

- Specifications live in `.start/specs/[NNN]-[name]/` (legacy: `docs/specs/`):

- - `requirements.mdx` — **WHY**: problem, users, acceptance criteria

- - `solution.mdx` — **WHAT (design)**: target architecture, components, interfaces

- - `plan.mdx` — **WHAT (narrative)**: the high-level approach — phases and achievable outcomes, plus a link to the tracker. Read for orientation, not parsed for work.

- - `.tracker/` — the operational **tasks** (managed by `task.js`): a root **phase** task, one **slice** task per vertical deliverable (its body is the code brief — features + EARS behavior + quality gates), and under each slice its **scenario** child tasks (the holdout acceptance evidence). `--depends-on` edges between slices are the parallelization contract.

-

- The specification carries **no task-by-task instructions** — a slice says what it delivers and how it is proven, never the steps to build it. `/start:specify` runs Requirements → Solution → Plan (a 5-step flow: init → requirements → solution → plan → finalize); `specify-plan` writes the narrative `plan.mdx` and creates the tracker tasks.

-

- #### One implementation loop (the dynamic-workflow runtime)

-

- There is a single `/start:implement`, and it always runs on Claude Code's **dynamic-workflow runtime**. It reads the spec's tasks from the tracker, installs one reusable workflow into the project at `.claude/workflows/implement.js` (a bundled golden copy — `implement/reference/implement.js` — carrying a version marker; it prompts to upgrade when the bundled copy is newer), and launches it with the slice tasks as input.

-

- The workflow drives each slice through a **barriered code→eval retry loop**:

- - a **code agent** builds the slice via TDD — it reads the slice task (features + EARS + gates), never its scenario child tasks;

- - an **eval agent** proves the slice against its scenario child tasks through external interfaces — it reads the scenarios + service config, never the slice or the source;

- - failures are filtered to one-line summaries and fed back until the slice's scenarios pass the `threshold`, or `max_iterations` is reached; each failed scenario becomes a `type: bug` child task.

-

- The information barrier is *which task each agent reads* — the code agent the slice, the eval agent its scenario children. Independent slices (no unmet dependency) run concurrently via the runtime's `parallel()`; dependent slices run in order. Scale is emergent — a 1-slice plan is a short loop, a 40-slice plan fans out. Specs created before this model (legacy `### BEAN-N` plans, `plan/` / `manifest.md`) are not run; `/start:implement` offers to re-run `/start:specify` to regenerate the tasks. Users invoke `/start:specify` and `/start:implement`; everything else is internal.

-

- ### Knowledge Capture

-

- Discovered patterns, interfaces, and domain rules are automatically documented in:

- - `docs/patterns/` - Technical patterns

- - `docs/interfaces/` - External integrations

- - `docs/domain/` - Business rules

-

- ### Constitution Enforcement

-

- Optional `CONSTITUTION.md` at project root defines checkable rules:

- - L1 (Must) - Blocking with autofix

- - L2 (Should) - Blocking, manual fix

- - L3 (May) - Advisory only

-

- ## File Naming Conventions

-

- | Type | Location | Naming |

- |------|----------|--------|

- | Commands | `plugins/*/commands/*.md` | lowercase-kebab (e.g., `specify.md`) |

- | Skills | `plugins/*/skills/*/SKILL.md` | directory is skill name |

- | Agents | `plugins/team/agents/the-*/` | `the-[role]/[activity].md` |

- | Output Styles | `plugins/*/output-styles/*.md` | Title Case (e.g., `The Startup.md`) |

- | Specs | `.start/specs/[NNN]-*/` | 3-digit ID prefix |

-

- ## Publishing

-

- The repository is a Claude Code marketplace. Publishing happens via:

- 1. Push to `main` branch

- 2. GitHub Actions workflow creates release

- 3. Users install via `/plugin marketplace add rsmdt/the-startup`