@vpxa/aikit 0.1.126 → 0.1.127

package/scaffold/README.md

@@ -1,228 +0,0 @@
-# Scaffold System — Contributor Guide
-
-> **⚠️ GOLDEN RULE: Never edit files in `scaffold/general/` or `scaffold/claude-code/` directly.**
-> They are **generated output** and will be overwritten by `generate.mjs`.
-> Always edit the **source files** in `scaffold/definitions/`.
-
-## Architecture
-
-```
-scaffold/
-├── definitions/          ← SOURCE OF TRUTH (edit here)
-│   ├── agents.mjs        Agent metadata (name, description, model, tools, category)
-│   ├── bodies.mjs        Agent body text (mode instructions per agent)
-│   ├── flows.mjs         Flow step instruction content (step READMEs as JS strings)
-│   ├── skills.mjs        Skill content (SKILL.md + reference files as JS strings)
-│   ├── models.mjs        Available models per IDE
-│   ├── protocols.mjs     Shared protocol files (_shared/*.md) + templates
-│   ├── tools.mjs         Tool capability → IDE tool mappings
-│   ├── prompts.mjs       Prompt file content
-│   ├── hooks.mjs         Hook definitions
-│   └── plugins.mjs       Plugin definitions
-│
-├── adapters/             ← IDE-specific generators
-│   ├── copilot.mjs       GitHub Copilot adapter (active — generates ~32 files)
-│   ├── claude-code.mjs   Claude Code adapter (stub — no output yet)
-│   ├── flows.mjs         Flow step file generator (reads definitions/flows.mjs)
-│   └── skills.mjs        Skill file generator (reads definitions/skills.mjs)
-│
-├── generate.mjs          ← BUILD SCRIPT (run after any change)
-│
-├── general/              ← GENERATED OUTPUT for Copilot (DO NOT EDIT)
-│   ├── agents/
-│   │   ├── _shared/      Protocol files (from PROTOCOLS in protocols.mjs)
-│   │   ├── templates/    Template files (from TEMPLATES in protocols.mjs)
-│   │   └── *.agent.md    Agent files (from AGENT_BODIES in bodies.mjs)
-│   └── prompts/          Prompt files (from PROMPTS in prompts.mjs)
-│
-└── claude-code/          ← GENERATED OUTPUT for Claude Code (stub, DO NOT EDIT)
-```
-
-### Data Flow
-
-```
-definitions/*.mjs  →  generate.mjs  →  scaffold/general/  →  aikit init  →  .github/ (user project)
-    (source)          (build script)    (generated output)    (deploy)     (user workspace)
-```
-
-## How to Make Changes
-
-### Step 1: Edit Source Files
-
-| What you want to change | Edit this file |
-|--------------------------|---------------|
-| An agent's body/instructions | `definitions/bodies.mjs` → `AGENT_BODIES[agentName]` |
-| Shared rules for code agents | `definitions/protocols.mjs` → `PROTOCOLS['code-agent-base']` |
-| Shared rules for researchers | `definitions/protocols.mjs` → `PROTOCOLS['researcher-base']` |
-| Agent metadata (model, tools) | `definitions/agents.mjs` → `AGENTS[agentName]` |
-| Flow step instructions | `definitions/flows.mjs` → `FLOWS['<flow-name>']` find the step file entry |
-| Skill content | `definitions/skills.mjs` → `SKILLS['<skill-name>']` find the file entry |
-| Available models | `definitions/models.mjs` |
-| Tool mappings | `definitions/tools.mjs` |
-| Prompt files | `definitions/prompts.mjs` |
-
-### Step 2: Regenerate Output
-
-```bash
-node scaffold/generate.mjs
-```
-
-This will:
-1. Clean `general/agents/` and `general/prompts/` directories
-2. Regenerate all files from definitions via the copilot adapter
-3. Print every file written (expect ~32 files)
-
-To generate for a specific IDE only:
-```bash
-node scaffold/generate.mjs --ide copilot
-node scaffold/generate.mjs --ide claude-code
-```
-
-### Step 3: Verify
-
-```bash
-# Syntax check the source file you edited
-node -e "import('./scaffold/definitions/bodies.mjs')"
-node -e "import('./scaffold/definitions/flows.mjs')"
-
-# Verify your changes appear in generated output
-# (use grep/Select-String for key phrases)
-grep -r "your key phrase" scaffold/general/agents/
-```
-
-### Step 4: Commit Both Source AND Generated
-
-Always commit the definition source files AND the regenerated output together.
-The generated files are checked into git so `aikit init` can deploy them without
-running the generator.
-
-## Source File Details
-
-### bodies.mjs
-
-Contains `AGENT_BODIES` — an object mapping agent names to their body text.
-
-- Most values are **template literal strings** (`` `...` ``)
-- The **Orchestrator** body is a **function** `(agentTable) => string` because it
-  dynamically includes the agent roster table
-- Backticks inside content must be escaped: `` \` ``
-
-```js
-export const AGENT_BODIES = {
-  Orchestrator: (agentTable) => `# Orchestrator\n${agentTable}\n...`,
-  Implementer: `# Implementer\n...`,
-  Debugger:    `# Debugger\n...`,
-  // ...
-};
-```
-
-### flows.mjs
-
-Contains `FLOWS` — flow step instruction content for all builtin flows.
-
-- Keys are flow names: `'aikit-advanced'`, `'aikit-basic'`, `'_epilogue'`
-- Each value is an array of `{ file, content }` objects — one per step README
-- `file` is the relative path (e.g. `'steps/plan/README.md'`)
-- `content` is the markdown string (escape backticks as `` \` ``)
-
-```js
-export const FLOWS = {
-  'aikit-advanced': [
-    { file: 'steps/plan/README.md', content: `# Planning\n...` },
-    ...
-  ],
-};
-```
-
-### skills.mjs
-
-Contains `SKILLS` — content for all builtin skills.
-
-- Keys are skill names: `'aikit'`, `'brainstorming'`, `'typescript'`, etc.
-- Each value is an array of `{ file, content }` objects — SKILL.md + reference files
-- Edit content inline; no markdown files to maintain separately
-
-### protocols.mjs
-
-Contains `PROTOCOLS` and `TEMPLATES` — objects mapping names to markdown content.
-
-- Each `PROTOCOLS` key becomes a file in `_shared/`:
-  - `'code-agent-base'` → `agents/_shared/code-agent-base.md`
-  - `'researcher-base'` → `agents/_shared/researcher-base.md`
-  - `'decision-protocol'` → `agents/_shared/decision-protocol.md`
-  - etc.
-- Each `TEMPLATES` key becomes a file in `templates/`
-- All values are template literals — escape backticks as `` \` ``
-
-**Protocol → Agent mapping:**
-
-| Protocol | Used by |
-|----------|---------|
-| `code-agent-base` | Implementer, Frontend, Refactor, Debugger |
-| `researcher-base` | Researcher-Alpha/Beta/Gamma/Delta |
-| `code-reviewer-base` | Code-Reviewer-Alpha/Beta |
-| `architect-reviewer-base` | Architect-Reviewer-Alpha/Beta |
-| `decision-protocol` | Referenced by Orchestrator workflow |
-| `forge-protocol` | Referenced by code-agent-base |
-
-### agents.mjs
-
-Defines every agent's metadata:
-- `description`, `argumentHint` — displayed in the agent picker
-- `model` — which LLM model to use
-- `tools` — abstract capability list (mapped to IDE-specific tools by the adapter)
-- `category` — orchestration, implementation, diagnostics, research, review, etc.
-- `sharedBase` — for variant agents (e.g., Researcher-Alpha uses `researcher-base`)
-
-## How Users Receive Changes
-
-When users run `aikit init`, the scaffold files are deployed to their `.github/` directory.
-
-### First Install (Legacy Path)
-
-`copyDirectoryRecursive()` — copies all scaffold files, **skips existing** files.
-No tracking, no merging.
-
-### Updates (Smart Path)
-
-`smartCopyScaffold()` — manifest-based with `.aikit-scaffold.json`:
-
-| File Status | Strategy | Behavior |
-|-------------|----------|----------|
-| `new` (not in manifest, not on disk) | deploy | Copy file, record hash |
-| `new` (not in manifest, exists on disk) | record | Record hash only (preserve user edits) |
-| `outdated` (source hash changed) | `merge-frontmatter` | **Agent files**: update body, union tools, keep user's model choice |
-| `outdated` (source hash changed) | `overwrite` | **Protocol/shared files**: replace entirely |
-| `current` (unchanged) | skip | No action |
-
-The update strategy is determined by `getUpdateStrategy(relPath)` based on the file path.
-
-**Key implication**: When you update an agent body in `bodies.mjs`, existing users will
-get the updated body text while preserving their custom model choice and any extra tools
-they added. Protocol files (`_shared/*.md`) are fully replaced.
-
-## Common Mistakes
-
-| Mistake | Why it's wrong | What to do instead |
-|---------|---------------|-------------------|
-| Editing deployed files directly (e.g. `~/.copilot/skills/`, `~/.github/agents/`) | These are **deploy targets**, not source. Changes will be overwritten on next `aikit init` or `generate.mjs` run | Always edit in `scaffold/definitions/` -> run `generate.mjs` -> then `aikit init` to deploy |
-| Editing `.agent.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `bodies.mjs` for agent bodies |
-| Editing `_shared/*.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `protocols.mjs` PROTOCOLS constant |
-| Editing flow step content in `_preview/flows/` | Will be overwritten by `generate.mjs` | Edit `definitions/flows.mjs` |
-| Editing skill content in `_preview/skills/` | Will be overwritten by `generate.mjs` | Edit `definitions/skills.mjs` |
-| Forgetting to run `generate.mjs` | Generated files will be stale, `aikit init` deploys stale files | Always run after editing definitions |
-| Committing only source OR only generated | Source and output will be out of sync | Commit both together |
-| Unescaped backticks in template literals | JS syntax error in definitions | Use `` \` `` inside template literal strings |
-
-## PR Checklist
-
-- [ ] Changes made in `scaffold/definitions/*.mjs` (NOT in generated output)
-- [ ] `node scaffold/generate.mjs` runs without errors
-- [ ] Generated output contains expected changes (verified with grep)
-- [ ] Both source and generated files included in commit
-- [ ] If adding a new agent: entry in `agents.mjs` + body in `bodies.mjs`
-- [ ] If adding a new protocol: entry in `protocols.mjs` + reference in relevant agent bodies
-- [ ] If adding/updating a flow step: edit `definitions/flows.mjs` → correct `FLOWS` entry
-- [ ] If adding/updating a skill: edit `definitions/skills.mjs` → correct `SKILLS` entry
-- [ ] If adding a new file type: check `getUpdateStrategy()` returns correct merge strategy
-- [ ] Consider impact on existing user installations (will merge preserve their customizations?)