@axis-bootstrap/cli 0.1.0

package/templates/bootstrap-skill/references/PHASE-2-SPEC.md

@@ -0,0 +1,250 @@
+# Phase 2 — Spec Layer Generation
+
+**Goal:** generate the project's single source of knowledge (`.ai/`).
+
+**Input:** Project Profile validated in Phase 1.
+
+**Output:** `.ai/` structure populated with `INSTRUCTIONS.md`, skill skeletons, initial rules, and doc stubs.
+
+---
+
+## Generation Order (do not reverse)
+
+```text
+1. Create folder structure
+2. Generate INSTRUCTIONS.md
+3. Generate skill skeletons (one per identified domain)
+4. Generate initial rules
+5. Generate doc stubs
+6. Present to user and validate
+```
+
+---
+
+## Step 1 — Folder Structure
+
+```bash
+mkdir -p .ai/{skills,rules,docs,docs/stories}
+```
+
+For non-technical projects, still create the structure — `rules/` can be used for "protocols", `docs/` for domain references. Homogeneity simplifies maintenance.
+
+---
+
+## Step 2 — INSTRUCTIONS.md
+
+Use the template from [TEMPLATES.md → INSTRUCTIONS.md](TEMPLATES.md#instructionsmd).
+
+**Section order (consultation frequency, not logical importance):**
+
+1. **Purpose** (1-2 sentences — what it does, for whom, why)
+2. **Stack or Tools** (with relevant versions)
+3. **How to Run / How to Start** (exact commands or first steps)
+4. **Architecture** (table: component → responsibility → technology → location)
+5. **Design Principles** (3-7 bullets with short rationale)
+6. **Conventions** (summary — details in rules)
+7. **Available Skills** (table: skill → when to use)
+8. **Links** (to detailed docs)
+
+**Target size:** 100-180 lines. Below 100 is superficial; above 200 loses focus.
+
+**Critical insight — describe decisions, not just facts:**
+
+```markdown
+# Bad
+- ORM: TypeORM
+
+# Good
+- ORM: TypeORM with Repository pattern — never access `Repository<T>` directly in services,
+  encapsulate in `*Repository` classes to make mocking in tests easier
+```
+
+The second form saves a question to the dev and prevents out-of-pattern code.
+
+**For non-technical projects**, replace:
+
+- "Stack" → "Tools and platforms"
+- "How to run" → "How to start / workflow"
+- "Architecture" → "Project components"
+- "Code conventions" → "Quality standards"
+
+---
+
+## Step 3 — Skill Skeletons
+
+For each domain identified in Phase 1, create:
+
+```text
+.ai/skills/<name>/
+└── SKILL.md         (40-60 lines, without references/ yet)
+```
+
+Use template [SKILL.md in TEMPLATES.md](TEMPLATES.md#skillmd-index).
+
+**The frontmatter `description` is the most critical element** — determines whether the skill will be loaded. Checklist:
+
+- [ ] 2-4 lines (1 line is vague, 5+ is excessive)
+- [ ] In third person ("Use when implementing...")
+- [ ] Mentions domain terms that act as triggers
+- [ ] Lists 3-5 usage scenarios
+- [ ] A new dev would understand when to use the skill just by reading the description
+
+```yaml
+# Weak
+description: Reference for the payments API integration.
+
+# Strong
+description: Complete reference for the Payments API integration.
+  Use when implementing API calls (endpoints, auth, payload format),
+  debugging API responses (error codes, rate limits),
+  or understanding the retry strategy and idempotency rules.
+```
+
+**Do not populate references/ yet.** This phase delivers the index. References are filled in subsequent sessions as knowledge accumulates.
+
+### Granularity — when to create new skill vs expand existing
+
+**Create new when:**
+- Domain has >5 specific concepts
+- Has its own workflow
+- Usage scenario is distinct
+
+**Expand existing when:**
+- Information is complementary
+- SKILL.md still <60 lines after addition
+- Same usage scenario
+
+**Use `docs/` instead of skill when:**
+- It is pure reference documentation (schema, contracts)
+- Does not involve workflow
+- Will be referenced by multiple skills
+
+---
+
+## Step 4 — Initial Rules
+
+For software projects, create 3-7 rules in `.ai/rules/`. Use template [Rule in TEMPLATES.md](TEMPLATES.md#code-rule).
+
+**Recommended default structure:**
+
+```text
+.ai/rules/
+├── code-style.md            (naming, formatting, imports)
+├── architecture-patterns.md (DI, modules, framework patterns)
+├── database.md              (ORM, migrations, queries)
+├── testing.md               (test structure, mocks)
+└── cli.md                   (commands and scripts)
+```
+
+**Frontmatter for scope:**
+
+```yaml
+---
+applyTo: "**/*.{ext}"
+paths:
+  - "src/**"
+---
+```
+
+**How to write an effective rule:**
+
+```markdown
+# Bad — too generic
+- Use meaningful variable names
+- Keep functions small
+
+# Good — specific and actionable
+- Use constants or enums for all fixed domain values (e.g., `Status`, `Origin`)
+  — never use string literals like `'pending'` scattered in the code
+- Batch operations: prefer native ORM/DB bulk inserts/updates — never loops
+  (impact of N+1 queries on large tables is exponential)
+```
+
+**Three elements of an effective rule:** what to do, how to do it, and why (when not obvious).
+
+**For non-technical projects**, replace rules with **protocols** (same structure, without `applyTo`):
+
+```text
+.ai/rules/  (or .ai/protocols/)
+├── tone-of-voice.md
+├── article-structure.md
+├── review-checklist.md
+└── citation-standards.md
+```
+
+---
+
+## Step 5 — Doc Stubs
+
+Create files with headers and empty sections, ready for future population.
+
+### For software
+
+```text
+.ai/docs/
+├── architecture.md          (system overview + decisions)
+├── database-schema.md       (tables + business rules + indexes)
+├── api-contracts.md         (internal and external contracts)
+├── data-flows.md            (optional — for non-obvious flows)
+└── monitoring.md            (optional — observability)
+```
+
+`architecture.md` should include a **Key Architectural Decisions** section with format:
+
+```markdown
+- **Why <decision>:** <short rationale>
+```
+
+`database-schema.md` should include **business rules** alongside the schema (not elsewhere):
+
+```markdown
+**Business rules:**
+- `deleted_at IS NULL` in all queries (soft delete)
+- `retry_count` incremented on each failed attempt, max 3
+```
+
+### For specialized domains (non-software)
+
+```text
+.ai/docs/
+├── glossary.md              (domain terms with specific meaning)
+├── workflows.md             (work flows)
+└── references.md            (external links, official sources)
+```
+
+---
+
+## Step 6 — Validation and Gate
+
+Present to user:
+
+```markdown
+## Spec Layer Generated
+
+### Structure
+.ai/INSTRUCTIONS.md (N lines)
+.ai/skills/<skill1>/SKILL.md (N lines)
+.ai/skills/<skill2>/SKILL.md (N lines)
+...
+.ai/rules/<rule1>.md
+.ai/docs/architecture.md (stub)
+...
+
+### Total
+- N skills initialized
+- N rules created
+- N doc stubs
+
+### Question
+Any critical domain I missed? Any file that doesn't make sense for this project?
+Any name to adjust?
+```
+
+**Wait for confirmation before Phase 3.**
+
+---
+
+## Quality Principles
+
+- **Density > length** — every line must carry useful information
+- **Decisions > facts** — explain the "why", not just the "what"

package/templates/bootstrap-skill/references/PHASE-3-HARNESS.md

@@ -0,0 +1,331 @@
+# Phase 3 — Harness Layer Configuration
+
+**Goal:** install the behavioral infrastructure that makes the agent safe, consistent, and productive regardless of what the model "decides" in the moment.
+
+**Input:** Spec Layer from Phase 2 validated + project type.
+
+**Output:** versioned `settings.json`, configured hooks, declared sub-agents, distributed symlinks.
+
+---
+
+## Why the Harness Exists
+
+The spec defines what the agent knows. **But production reliability depends more on the harness than on the model.** Without it:
+
+- Inconsistent formatting accumulates in dirty diffs
+- Destructive commands go through (`rm -rf`, `DROP TABLE`)
+- Tests don't run at the end, regressions escape
+- Each developer gets different AI behavior per machine
+
+The harness eliminates each of these by construction, not by discipline.
+
+---
+
+## The Five Subsystems
+
+| Subsystem                 | Function                             | Applicability                     |
+| ------------------------- | ------------------------------------ | --------------------------------- |
+| **Permission Harness**    | Versioned `settings.json`            | Universal                         |
+| **Execution Harness**     | Hooks (Pre/Post/Stop)                | Software (with adaptations)       |
+| **Orchestration Harness** | Sub-agents                           | Universal                         |
+| **Context Harness**       | Token budget, Progressive Disclosure | Universal (already in Phase 2)    |
+| **Verification Harness**  | Quality gates in skills              | Universal (already in Phase 2)    |
+
+This phase implements the first three (the other two are already in the Phase 2 design).
+
+---
+
+## Step 1 — `settings.json`
+
+Use the template in [TEMPLATES.md → settings.json](TEMPLATES.md#settingsjson). Adapt to the stack via table:
+
+| Stack       | Replace `<build-tool>` with                       |
+| ----------- | ------------------------------------------------- |
+| Node.js     | `Bash(npm *)`, `Bash(npx *)`                      |
+| Python      | `Bash(pip *)`, `Bash(pytest *)`, `Bash(poetry *)` |
+| Go          | `Bash(go *)`                                      |
+| Java/Maven  | `Bash(mvn *)`                                     |
+| Java/Gradle | `Bash(gradle *)`, `Bash(./gradlew *)`             |
+| Ruby        | `Bash(bundle *)`, `Bash(rake *)`                  |
+| PHP         | `Bash(composer *)`                                |
+| Rust        | `Bash(cargo *)`                                   |
+| .NET        | `Bash(dotnet *)`                                  |
+
+**Minimum structure:**
+
+```json
+{
+  "permissions": {
+    "allow": ["Read", "Bash(git *)", "<stack>", "Edit(/src/**)", "Edit(/.ai/**)"],
+    "deny": ["Bash(rm -rf *)", "Bash(git push --force*)"],
+    "ask": ["Bash(git push *)", "Edit(/.env*)"]
+  }
+}
+```
+
+**Universal (non-software):** keep `Read`, `Bash(git *)`, `Edit(/.ai/**)`, and adapt `Edit` to the project layout. Skip stack entries.
+
+**Versioning in git** is mandatory. Without it, behavior varies per machine and bugs are hard to reproduce.
+
+---
+
+## Step 2 — Hooks
+
+Hooks execute shell commands in response to agent events. **Three are indispensable** when applicable:
+
+### Hook A — `PostToolUse` (automatic formatting)
+
+**Applicable to:** software with a formatter.
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/format-file.sh \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Script `format-file.sh` in [TEMPLATES.md → format-file.sh](TEMPLATES.md#format-filesh). It is stack-aware via `case` and never fails (`exit 0`) — missing formatter does not block the agent.
+
+**Why indispensable:** without it, diffs get polluted with style changes, increasing code review cost.
+
+### Hook B — `PreToolUse` (destructive blocking)
+
+**Applicable to:** universal. Always install.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "bash scripts/validate-bash.sh" }]
+      }
+    ]
+  }
+}
+```
+
+Script `validate-bash.sh` in [TEMPLATES.md → validate-bash.sh](TEMPLATES.md#validate-bashsh). Blocks patterns: `rm -rf /`, `DROP TABLE`, `TRUNCATE`, `DELETE FROM` without WHERE.
+
+**Why indispensable:** the agent occasionally infers it needs to "clean up" files. Without protection, a context error is irreversible. Does not block normal work — only the dangerous cases.
+
+### Hook C — `Stop` (tests on finish)
+
+**Applicable to:** software with a test runner.
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/run-tests-if-changed.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Script `run-tests-if-changed.sh` in [TEMPLATES.md → run-tests-if-changed.sh](TEMPLATES.md#run-tests-if-changedsh). Detects changed extensions in the diff and runs only the applicable test runner.
+
+**Why indispensable:** closes the feedback loop. The agent not only "does" — it validates what it did. Regressions are caught in the same session.
+
+### For non-technical projects
+
+- **Hook A:** skip (no formatter)
+- **Hook B:** **keep** (universal protection)
+- **Hook C:** skip or replace with output validation (e.g., spell check, markdown lint)
+
+---
+
+## Step 3 — Sub-agents
+
+Sub-agents enable smart delegation. The main agent **orchestrates**, sub-agents **execute**.
+
+### `Explore` (built-in, always enable)
+
+- Read-only access: `Glob`, `Grep`, `Read`, `WebFetch`, `WebSearch`
+- Cannot edit files during research
+- More efficient: does not load unused write tools
+- For large codebases, use level `"very thorough"`
+
+### When to delegate vs execute
+
+| Task                              | Delegate? | Why                                  |
+| --------------------------------- | --------- | ------------------------------------ |
+| Research / exploration            | **Yes**   | Bulky output; only the summary matters |
+| Task implementation               | **Yes**   | File reads/edits consume context     |
+| Independent parallel tasks        | **Yes**   | Only way to parallelize              |
+| Sequential tasks without dependencies | **Yes** | Keeps main context clean            |
+| Planning and task creation        | **No**    | Requires accumulated context         |
+| Validation and final reports      | **No**    | Needs session history                |
+| Quick fixes (≤3 files)            | **No**    | Overhead > task                      |
+
+### Sub-agent contract
+
+**Receives:**
+- Task definition (what to do, where, completion criteria)
+- Relevant rules and conventions
+- Spec/design the task references
+
+**Does not receive:**
+- Definitions of other tasks
+- Accumulated chat history
+- `STATE.md` (unless recording a specific decision/blocker)
+
+**Returns:**
+- Status: Complete | Blocked | Partial
+- Changed files
+- Test/validation result
+- Issues found
+
+---
+
+## Step 4 — Symlinks by IDE
+
+For each IDE declared in Phase 1, create symlinks. Use the script [setup-ide-links.sh in TEMPLATES.md](TEMPLATES.md#setup-ide-linkssh).
+
+**Principle:** the script is **idempotent** (`ln -sf` replaces without error). Can run as many times as needed.
+
+**Target folder by IDE:**
+
+| IDE            | Where it looks for context                                 |
+| -------------- | ---------------------------------------------------------- |
+| Claude Code    | `.claude/`, `CLAUDE.md`                                    |
+| Cursor         | `.cursor/rules/`, `.cursor/skills/`, `AGENTS.md`           |
+| GitHub Copilot | `.github/copilot-instructions.md`, `.github/instructions/` |
+| Windsurf       | `AGENTS.md`, `.agents/`                                    |
+
+**Skip** symlinks for IDEs the user declared not using — reduces noise in `git status`.
+
+**Smoke test after creating:**
+
+```bash
+ls -la CLAUDE.md AGENTS.md .claude/ .cursor/ .agents/ .github/
+```
+
+Each symlink should show `→ ../.ai/...` or similar.
+
+### Windows
+
+Symlinks on Windows require administrator permission or Developer Mode enabled. If the team uses Windows:
+
+- Document in `INSTRUCTIONS.md` or `CONVENTIONS.md`
+- Recommend `core.symlinks = true` in Git for Windows
+- Alternative: use `mklink /D` in elevated terminal
+
+---
+
+## Step 5 — Smoke Test and Gate
+
+```bash
+# 1. Verify settings.json
+cat .claude/settings.json | jq .   # or cat if no jq
+
+# 2. Verify symlinks resolve
+ls -la CLAUDE.md AGENTS.md
+
+# 3. Verify hooks execute (create dummy file and watch lint run)
+echo "test" > /tmp/test.ts && bash scripts/format-file.sh /tmp/test.ts
+```
+
+Present to user:
+
+```markdown
+## Harness Layer Configured
+
+### Permissions
+- N entries in allow, N in deny, N in ask
+
+### Hooks installed
+- PostToolUse: format-file.sh (Node/Python/Go per stack)
+- PreToolUse: validate-bash.sh (destructive protection — universal)
+- Stop: run-tests-if-changed.sh
+
+### Symlinks created
+[visual tree]
+
+### Smoke test
+[output of the 3 commands above]
+
+### Question
+Any additional destructive patterns to block? Any missing IDE?
+```
+
+**Wait for confirmation before Phase 4.**
+
+---
+
+## Step 6 — Failure Attribution
+
+> **Context:** ReliabilityBench (arxiv 2601.06112) demonstrated that pass@1 overestimates reliability by 20-40%. AgentProp-Bench (arxiv 2604.16706) showed that most benchmarks report only pass/fail, without locating where in the pipeline the failure occurred. AXIS instruments the harness for attribution.
+
+**Configure structured logging in `settings.json`:**
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"{\\\"event\\\":\\\"pre\\\",\\\"tool\\\":\\\"$CLAUDE_TOOL_NAME\\\",\\\"ts\\\":\\\"$(date -Iseconds)\\\"}\" >> .ai/logs/harness.jsonl 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"{\\\"event\\\":\\\"post\\\",\\\"tool\\\":\\\"$CLAUDE_TOOL_NAME\\\",\\\"exit\\\":\\\"$CLAUDE_TOOL_EXIT_CODE\\\",\\\"ts\\\":\\\"$(date -Iseconds)\\\"}\" >> .ai/logs/harness.jsonl 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Add `.ai/logs/` to `.gitignore` (they are runtime logs, not versioned).
+
+**Failure attribution table:**
+
+| Category      | Symptom                                   | Signal in log                           | Action                                                             |
+| ------------- | ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------ |
+| **Planning**  | Agent attempts to execute without clear criteria | PreToolUse without corresponding spec task | Review `INSTRUCTIONS.md`; add acceptance criteria to skill |
+| **Execution** | Tool call fails repeatedly                | PostToolUse with `exit != 0` in loop    | Review `settings.json`; adjust allow/deny                          |
+| **Response**  | Output generated but wrong format         | Phase 5 gate rejects                    | Add output example to skill template                               |
+
+**Add to Phase 5 checklist:**
+- [ ] `harness.jsonl` exists and records events after smoke test
+- [ ] No tool call loop with exit != 0 detected
+
+---
+
+## Unifying Principle
+
+The gain from hooks: **removes dependency on manual discipline.** The formatter runs because the hook exists, not because the developer remembered. Tests run because `Stop` was configured, not because the agent decided to. Destructive commands are blocked because the rule exists, not because the agent "was careful".
+
+**Production failures are not opaque** — the instrumented harness locates whether the problem is in planning (vague spec), execution (invalid tool call) or response (wrong format). This eliminates trial-and-error debugging.
+
+Spec defines what the agent knows. Harness ensures it acts consistently, safely, and traceably — regardless of the conversation context.