2026-03-01 12:24:11 -08:00
# Development Commands
> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.
## Common Commands
```bash
# Install dev dependencies (sets up husky pre-commit hooks)
npm install
2026-08-20 13:42:43 -07:00
# Run the interactive installer
2026-03-01 12:24:11 -08:00
node install.js
2026-08-20 13:42:43 -07:00
# Regenerate skills/ from src/ (non-interactive)
npm run build:skills
# Character-count validation + skills/ drift check
npm test
2026-03-01 12:24:11 -08:00
# Plan2Code Loop
cd plan2code-loop && npm install # First time setup
cd plan2code-loop && npm run build # Build the CLI
# Plan2Code Metrics
cd plan2code-metrics && npm install # First time setup
cd plan2code-metrics && npm run build # Build the CLI
```
## Installer Menu Options
**Main menu:**
| Option | Action |
|--------|--------|
2026-08-20 13:42:43 -07:00
| `I` | Install the Plan2Code skills globally through the skills CLI — **skills only** , no dev tools |
| `A` | Everything in `I` plus `plan2code-loop` , `plan2code-bot` , `plan2code-metrics` , and the Claude Code status line |
| `U` | Uninstall Plan2Code skills and all dev tools (confirmation required) |
2026-03-01 12:24:11 -08:00
| `C` | Open CUSTOM sub-menu |
| `Q` | Quit |
**CUSTOM sub-menu (`C`):**
| Option | Action |
|--------|--------|
2026-08-20 13:42:43 -07:00
| `L` | Install the skills into the current project instead of globally |
2026-03-01 12:24:11 -08:00
| `O` | Install plan2code-loop CLI only |
| `M` | Install plan2code-metrics CLI only |
2026-06-01 16:39:35 -07:00
| `S` | Install Claude Code status line only |
| `B` | Install plan2code-bot CLI only |
2026-03-01 12:24:11 -08:00
| `Q` | Return to main menu |
2026-08-20 13:42:43 -07:00
## Non-Interactive Flags
`install.js` takes no arguments for normal use, but exposes two build hooks. Any other argument exits 1 with usage.
| Flag | Action |
|------|--------|
| `--build-skills` | Regenerate `skills/` from `src/` , pruning stale skills and reference files |
| `--verify-skills` | Compare committed `skills/` with `src/` ; exits 1 on drift and is run by `npm test` |
2026-03-01 12:24:11 -08:00
## How the Installer Works
2026-08-20 13:42:43 -07:00
1. **Builds `skills/` from `src/`** — one Agent Skill per source prompt, including uncommitted source edits.
2. **Checks the skills CLI is reachable** with `npx --yes skills --version` .
3. **Sweeps pre-2.2 install paths** and removes installed `plan2code-*` skills so renamed or retired prompts cannot survive as orphans.
4. **Delegates installation** to `npx --yes skills add "<repo>/skills" -g -s <skill names> -y` .
2026-03-01 12:24:11 -08:00
2026-08-20 13:42:43 -07:00
The skills CLI owns distribution from step 4 onward. It stores canonical skills under `~/.agents/skills/` and links them into agents that maintain their own skill directory. Plan2Code no longer maintains platform-specific output formats.
2026-03-01 12:24:11 -08:00
2026-08-20 13:42:43 -07:00
**Invocation choices:**
| Choice | Reason |
|--------|--------|
| Explicit space-separated `-s <names>` | Avoids shell expansion and prevents unrelated directories under `skills/` from being installed. |
| No `-a` / `--agent '*'` | Uses the CLI's supported default agent set instead of requesting incompatible scope/agent combinations. |
| Captured output | Suppresses the CLI's duplicated banners while preserving real failures; unsupported-scope noise is filtered. |
## Skill Format
| Item | Value |
|------|-------|
| Path | `skills/<skill-name>/SKILL.md` |
| Skill name | `generateSkillName(prompt)` , such as `plan2code-1-plan` or `plan2code-init` |
| Frontmatter | `name` , `description` , `disable-model-invocation: true` |
| Reference files | `skills/<skill-name>/references/<file>.md` |
`disable-model-invocation: true` is unconditional because these workflows are user-initiated. Agents that do not recognize the field ignore it.
2026-03-01 12:24:11 -08:00
## Editing Workflow Prompts
2026-08-20 13:42:43 -07:00
`src/` is the source of truth; `skills/` is a committed build artifact.
2026-03-01 12:24:11 -08:00
2026-08-20 13:42:43 -07:00
1. Edit the source file under `src/` .
2. Run `npm run build:skills` .
3. Test the workflow in an AI tool.
4. Commit regenerated `skills/` beside the source change; `npm test` fails on drift.
5. Never edit `skills/` by hand because the next build overwrites it.
2026-07-20 22:31:37 -07:00
## Adding a New Workflow Prompt / Skill
2026-08-20 13:42:43 -07:00
1. Create `src/plan2code-<name>.md` with body content only and keep it under 11,000 characters.
2. Register it in `SOURCE_PROMPTS` in `install.js` ; add a matching `generateStepLabel()` case when needed.
3. Update command inventories in `README.md` , `QUICK-REFERENCE.md` , `.agents-docs/AGENTS-architecture.md` , and `CHANGELOG.md` . Update `docs/index.html` only for core pipeline steps.
4. Run `npm run build:skills` and `npm test` .