@axis-bootstrap/cli 0.1.0

package/templates/bootstrap-skill/references/PHASE-4-MEMORY.md

@@ -0,0 +1,187 @@
+# Phase 4 — Memory Layer Initialization
+
+**Goal:** ensure the project has continuity between sessions — decisions, state, and conventions persist even when the dev changes, the IDE changes, or time passes.
+
+**Input:** Spec Layer (Phase 2) and Harness Layer (Phase 3) confirmed.
+
+**Output:** two active memory artifacts in the project.
+
+---
+
+## Foundation: ACE Principle (Agentic Context Engineering)
+
+> Reference paper: **ACE — Agentic Context Engineering** (arxiv 2510.04618), which demonstrated +10.6% in agent benchmarks and +8.6% in finance with an approach that treats contexts as **evolutionary playbooks**.
+
+**What changes compared to a history log:**
+
+| Traditional approach           | ACE approach (AXIS)                           |
+| ------------------------------ | --------------------------------------------- |
+| Append-only: accumulates everything | Active curation: removes obsolete, elevates useful |
+| Grows indefinitely → noise     | Controlled size → focus                       |
+| History context                | Strategy context                              |
+| Session starts from zero       | Session starts informed                       |
+
+**Practical implication:** `STATE.md` is not a diary — it is a playbook. Each session the agent not only writes: it *refines*. Removes what was resolved. Elevates what proved useful. The result is that context *improves over time* instead of degrading.
+
+---
+
+## Why the Memory Layer Exists
+
+Without it, long-running projects regress with each session:
+
+- "Why did we decide X?" — lost
+- "What was in progress?" — redone from scratch
+- "What lesson did we learn from that bug?" — repeated
+- Spec Kit issue #75: "great specs but every new chat starts from zero"
+
+The Memory Layer is what makes the system **antifragile over time**.
+
+---
+
+## The Two Artifacts
+
+| Artifact         | Type                   | Update                                     |
+| ---------------- | ---------------------- | ------------------------------------------ |
+| `STATE.md`       | Live playbook (curated) | Each session — curate, not just append     |
+| `CONVENTIONS.md` | Meta (structure)        | When the `.ai/` structure changes          |
+
+---
+
+## Step 1 — `STATE.md`
+
+Create `.ai/docs/STATE.md` with **six mandatory sections**, even if they start empty:
+
+```markdown
+# Project State
+
+## Active Decisions
+<!-- [YYYY-MM-DD] Decision X made because Y -->
+
+## In Progress
+<!-- Feature Z: 70% complete, missing integration with API -->
+
+## Blockers
+<!-- API X returning 429 in staging — waiting for vendor response -->
+
+## Deferred Ideas
+<!-- Migrate to gRPC — evaluate when volume exceeds 10k req/min -->
+
+## Lessons Learned
+<!-- Bulk insert: use createQueryBuilder, not save() for >100 records -->
+
+## Pending TODOs
+- [ ]
+
+---
+
+## Handoff Protocol
+
+At the end of any session with relevant changes, the agent updates this file with:
+- What was done
+- What is left
+- Any context that would be lost
+
+At the start of a session, the agent reads this file **before** anything else.
+```
+
+**Ask the user before finalizing:**
+
+> "Are there decisions already made, current blockers, past lessons, or deferred ideas that should go into `STATE.md` before the first real session?"
+
+If there are, populate the sections with what the user provides. If not, leave with stub comments showing the expected format.
+
+### Session Handoff Protocol
+
+Document inside `STATE.md` (at the bottom, as instruction for the agent) — as shown in the template above.
+
+---
+
+## Step 2 — `CONVENTIONS.md`
+
+Create `.ai/CONVENTIONS.md`. Use template from [TEMPLATES.md → CONVENTIONS.md](TEMPLATES.md#conventionsmd). Minimum content:
+
+1. **Single Source of Truth principle** + symlink map
+2. **Templates** for creating new skills and rules (reference to TEMPLATES.md or local copy)
+3. **Rules for the agent:**
+   - Where to create files
+   - What never to do (duplicate between IDEs, create outside `.ai/`)
+4. **Knowledge Verification Chain** (codebase → docs → MCP/Context7 → web → mark as uncertain)
+5. **How to add support for new IDE** (3 `ln -s` commands)
+6. **Maintenance protocol** — triggers for updating docs
+
+---
+
+## Step 3 — Validation and Gate
+
+Present to user:
+
+```markdown
+## Memory Layer Initialized
+
+### Files created
+- .ai/docs/STATE.md (with 6 structured sections)
+- .ai/CONVENTIONS.md
+
+### STATE.md populated with
+- N active decisions
+- N items in progress
+- N blockers
+- N deferred ideas
+- N lessons
+- N TODOs
+
+### Next step
+Final validation in Phase 5.
+```
+
+**Wait for confirmation before Phase 5.**
+
+---
+
+## Maintenance Loop (document for future use)
+
+This section is recorded in `CONVENTIONS.md` for future reference:
+
+**Triggers for documentation updates:**
+
+| Event                                        | Expected agent action                          |
+| -------------------------------------------- | ---------------------------------------------- |
+| Code changes a skill's workflow              | Propose skill update before ending session     |
+| Architectural decision in the session        | Propose update to `architecture.md`            |
+| Business rule emerges                        | Ask whether to document in skill/docs          |
+| Bug reveals undocumented behavior            | Propose documenting                            |
+| New integration/dependency                   | Evaluate new skill or expansion                |
+| Session paused with work in progress         | Update `STATE.md`                              |
+
+**Principle:** the agent does not update automatically without confirmation, but does not let it pass without alerting either. Becomes **documentation guardian**.
+
+---
+
+## Anti-patterns
+
+- Leaving `STATE.md` with only stub comments without asking the user (misses the chance to capture fresh context)
+- Skipping `CONVENTIONS.md` as it seems "obvious" — it is what keeps the structure alive
+- **Appending without curating**: STATE.md with 500+ lines is a failure signal — context grows, focus shrinks
+
+---
+
+## ACE Curation Protocol
+
+At the end of **every** session with changes, execute in sequence:
+
+```markdown
+## STATE.md Curation
+
+1. Move to "Active Decisions" what was decided in this session
+2. Remove from "In Progress" what was completed
+3. Remove from "Blockers" what was resolved
+4. Add to "Lessons Learned" any non-obvious insight
+5. Move to "Deferred" ideas that won't be executed now
+```
+
+**STATE.md target size:** ≤ 80 lines. If exceeded, it signals that resolved items were not removed.
+
+**At session start:**
+1. Read STATE.md *before* anything else
+2. Check if "In Progress" reflects the current reality
+3. Update the date in the STATE.md header

package/templates/bootstrap-skill/references/PHASE-5-VALIDATION.md

@@ -0,0 +1,194 @@
+# Phase 5 — Validation & Handoff
+
+**Goal:** validate that the bootstrap delivered a complete, functional system and make a clear handoff to the user.
+
+**Input:** Phases 1-4 complete.
+
+**Output:** validation report + list of next steps.
+
+---
+
+## Audit Mode
+
+This phase also runs in standalone mode when the user asks to **audit an existing project**. In that case:
+
+- Skip Phases 1-4
+- Apply all checklists below
+- Report what is absent or out of standards
+- Do not create/modify anything without explicit confirmation
+
+---
+
+## Quality Gates — Structure
+
+```text
+[ ] .ai/ folder exists at project root
+[ ] .ai/INSTRUCTIONS.md exists and has 100-180 lines
+[ ] At least 3 skills in .ai/skills/, each with a SKILL.md
+[ ] Each SKILL.md has ≤ 60 lines
+[ ] Each SKILL.md has frontmatter with `name` and `description`
+[ ] Each `description` has 2-4 lines and mentions trigger terms
+[ ] For software projects: at least 3 rules in .ai/rules/ with `applyTo`
+[ ] At least 1 stub in .ai/docs/ (architecture.md, glossary.md, or equivalent)
+[ ] .ai/CONVENTIONS.md exists and contains symlink map
+[ ] .ai/docs/STATE.md exists with the 6 mandatory sections
+```
+
+---
+
+## Quality Gates — Harness
+
+```text
+[ ] settings.json exists and is versioned (git ls-files lists it)
+[ ] settings.json has allow/deny/ask filled coherently with the stack
+[ ] PreToolUse destructive blocking hook configured (universal)
+[ ] For software: PostToolUse hook with formatter configured
+[ ] For software: Stop hook with tests configured
+[ ] Scripts in scripts/ are executable (chmod +x)
+[ ] Scripts end with exit 0 (do not block the agent on failure)
+```
+
+---
+
+## Quality Gates — Symlinks
+
+```text
+[ ] CLAUDE.md → .ai/INSTRUCTIONS.md (resolves)
+[ ] AGENTS.md → .ai/INSTRUCTIONS.md (resolves)
+[ ] For each declared IDE: corresponding folder with correct symlinks
+[ ] setup-ide-links.sh exists and is idempotent
+[ ] Running setup-ide-links.sh twice generates no error
+[ ] ls -la shows expected targets in all symlinks
+```
+
+**Concrete smoke test:**
+
+```bash
+# Confirm that each symlink resolves without error
+for f in CLAUDE.md AGENTS.md .claude/CLAUDE.md .cursor/rules .cursor/skills; do
+  if [ -e "$f" ]; then
+    echo "OK: $f → $(readlink -f "$f")"
+  else
+    echo "MISSING: $f"
+  fi
+done
+```
+
+---
+
+## Quality Gates — Memory
+
+```text
+[ ] STATE.md has all 6 sections (Active Decisions, In Progress, Blockers,
+    Deferred Ideas, Lessons, TODOs)
+[ ] STATE.md mentions the handoff protocol
+[ ] CONVENTIONS.md describes where the AI can/cannot create files
+[ ] CONVENTIONS.md includes Knowledge Verification Chain
+```
+
+---
+
+## Quantitative Metrics
+
+Calculate and report:
+
+| Metric | Target | How to measure |
+| ------ | ------ | -------------- |
+| Lines in `INSTRUCTIONS.md` | 100-180 | `wc -l` |
+| Average lines per `SKILL.md` | 40-60 | `wc -l skills/*/SKILL.md \| awk` |
+| Total skills | 3-10 | `ls -d skills/*/ \| wc -l` |
+| Total rules | 3-7 (if software) | `ls rules/*.md \| wc -l` |
+| Active symlinks | equal to number of declared IDEs + 2 (root) | `find . -type l \| wc -l` |
+| Hooks installed | 1-3 | count in settings.json |
+
+**Problem signals:**
+
+- `INSTRUCTIONS.md` >200 lines → move details to skills/docs
+- Any `SKILL.md` >80 lines → move content to `references/`
+- >12 skills → excessive fragmentation, consider consolidation
+- No rules created in software project → probable gap
+
+---
+
+## Cross-Validation
+
+```text
+[ ] Skills mentioned in INSTRUCTIONS.md (table) exist in .ai/skills/
+[ ] Rules mentioned in INSTRUCTIONS.md exist in .ai/rules/
+[ ] Symlink map in CONVENTIONS.md matches the real symlinks
+[ ] IDEs declared in Phase 1 have corresponding folders
+```
+
+**If any cross-check fails**, fix before handoff.
+
+---
+
+## Handoff to User
+
+Final message follows template in [PROMPT-TEMPLATE.md](../PROMPT-TEMPLATE.md#handoff-to-user). Structure:
+
+```markdown
+## Bootstrap Complete
+
+### What was created
+- N files in .ai/
+- N skills initialized: <list>
+- N rules: <list>
+- N stubs in docs/
+- Memory layer with STATE, CONVENTIONS
+- N symlinks distributing to <IDEs>
+- N hooks in settings.json
+
+### Metrics
+- INSTRUCTIONS.md: N lines (target 100-180) ✓
+- SKILL.md average: N lines (target 40-60) ✓
+- Symlinks: all resolve ✓
+- Smoke tests: pass ✓
+
+### Suggested next steps (3-5)
+1. Detail the first priority skill — populate references/GUIDE.md in <skill>
+2. Validate settings.json with the team
+3. Configure CI to verify symlink resolution
+4. Test invocation by another IDE (multi-tool smoke test)
+
+### How to resume
+- Next session: agent reads STATE.md first
+- Future audit: invoke this skill again in "audit" mode
+- Add new IDE: edit setup-ide-links.sh + run
+```
+
+---
+
+## Acceptable vs Blocking Gaps
+
+**Acceptable** (report only, do not block):
+
+- references/ still empty in skills (expected — filled with use)
+- Domain-specific rules not yet written
+- docs/ stubs without content
+- Empty TODOs in STATE.md
+
+**Blocking** (fix before handoff):
+
+- INSTRUCTIONS.md absent or <50 lines
+- Skills without `description` in frontmatter
+- Broken symlinks
+- `settings.json` not versioned
+
+---
+
+## Post-Adoption Audit (future use)
+
+The user can re-invoke this skill weeks later to audit:
+
+```text
+"Use axis-bootstrap in audit mode on this project."
+```
+
+The agent:
+
+1. Skips Phases 1-4
+2. Applies all gates from this phase
+3. Identifies drift (e.g., INSTRUCTIONS.md grew to 250 lines; some skill lost description)
+4. Proposes corrections one by one
+5. **Does not correct without confirmation**

package/templates/bootstrap-skill/references/QUICKSTART.md

@@ -0,0 +1,144 @@
+# QUICKSTART — AXIS in 5 Minutes
+
+> For the full bootstrap (5 phases, 30 min), use the `axis-bootstrap` skill. This document is the fast path for those who want something working today and full structure later.
+
+---
+
+## What you'll have at the end
+
+- Contextual `INSTRUCTIONS.md` (not monolithic)
+- `settings.json` with destructive command blocking
+- Active multi-IDE symlinks
+- `STATE.md` with initial playbook
+- Base to expand to full bootstrap
+
+**Estimated time:** 5-10 minutes of interaction + 5 minutes of execution.
+
+---
+
+## Step 1 — Project identity (2 min)
+
+Answer mentally or paste the answers to the agent:
+
+1. **What does the project do?** (1 sentence)
+2. **Main stack/tools?** (or "non-technical" if content/research)
+3. **Which IDE(s) do you use?** (Claude Code / Cursor / Windsurf / Copilot — mark all)
+4. **Is there anything the agent should NEVER do?** (e.g., push directly to main, delete production data)
+
+---
+
+## Step 2 — Minimal `INSTRUCTIONS.md` (2 min)
+
+Create `.ai/INSTRUCTIONS.md` with this minimal structure (adapt):
+
+```markdown
+# [Project Name]
+
+[1-2 sentences about what the project does]
+
+## Stack
+- [main technology]
+- [other relevant ones]
+
+## How to run
+[start command]
+
+## Critical rules
+- Never [restriction 1 from previous step]
+- Always confirm before [destructive action]
+```
+
+> Limit: 50-80 lines for quick start. Expand to 100-180 in full bootstrap.
+
+---
+
+## Step 3 — Minimal `settings.json` (1 min)
+
+Create `.claude/settings.json` (or equivalent for your IDE):
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Bash(git status)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Edit(/.ai/**)"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(git push --force*)",
+      "Bash(DROP *)",
+      "Bash(truncate *)"
+    ],
+    "ask": [
+      "Bash(git push *)",
+      "Edit(/.env*)"
+    ]
+  }
+}
+```
+
+**Add to git immediately:** `git add .claude/settings.json && git commit -m "chore: add axis harness settings"`
+
+---
+
+## Step 4 — Multi-IDE symlinks (1 min)
+
+Run in terminal:
+
+```bash
+# At project root
+ln -sf .ai/INSTRUCTIONS.md CLAUDE.md
+ln -sf .ai/INSTRUCTIONS.md AGENTS.md
+mkdir -p .claude && ln -sf ../.ai/skills .claude/skills
+mkdir -p .cursor && ln -sf ../.ai/skills .cursor/skills
+mkdir -p .agents && ln -sf ../.ai/skills .agents/skills
+mkdir -p .github && ln -sf ../.ai/INSTRUCTIONS.md .github/copilot-instructions.md
+mkdir -p .github && ln -sf ../.ai/skills .github/skills
+```
+
+Verify: `ls -la CLAUDE.md AGENTS.md .claude/skills`
+
+---
+
+## Step 5 — Initial `STATE.md` (1 min)
+
+Create `.ai/docs/STATE.md`:
+
+```markdown
+# Project State
+
+## In Progress
+<!-- What is being done now -->
+
+## Blockers
+<!-- Nothing at the moment -->
+
+## Active Decisions
+<!-- [date] Adopted AXIS Framework -->
+
+## Lessons Learned
+<!-- Empty — to fill throughout the project -->
+
+---
+
+## Handoff Protocol
+
+At the end of sessions with relevant changes, update this file.
+At the start of a session, read this file before anything else.
+**Actively curate** — remove what is resolved.
+```
+
+---
+
+## Next Steps
+
+When you have 30 minutes: run the full bootstrap to create domain skills, automation hooks, and CONVENTIONS.md.
+
+```text
+Use the axis-bootstrap skill to complete the structure of this project.
+```
+
+The agent will detect the existing INSTRUCTIONS.md, skip Phase 1 (discovery already done), and complete the missing layers.