@axis-bootstrap/cli 0.1.0

package/templates/bootstrap-skill/references/UNIVERSAL-MAP.md

@@ -0,0 +1,216 @@
+# Universal Map — Technical ↔ Non-Technical
+
+The framework was originally designed for software projects, but its three layers (Spec, Harness, Memory) are **domain-agnostic**. This document maps technical concepts to universal equivalents, enabling application to any type of project.
+
+---
+
+## Translation Principle
+
+| Layer       | Universality   | What changes                                                       |
+| ----------- | -------------- | ------------------------------------------------------------------ |
+| **Spec**    | 100% universal | Only vocabulary (rules → protocols)                                |
+| **Harness** | ~70% universal | Lint/test hooks do not apply; permissions and blocks do            |
+| **Memory**  | 100% universal | Identical — STATE, CONVENTIONS work the same                       |
+
+The layer that varies most is the **Harness**, and even there the core (behavior versioning, destructive blocking, sub-agents) remains intact.
+
+---
+
+## Concept-to-Concept Mapping
+
+| Technical Concept         | Universal Equivalent                                    |
+| ------------------------- | ------------------------------------------------------- |
+| Technology stack          | Tools and platforms                                     |
+| Programming language      | Output format (markdown, spreadsheet, deck)             |
+| Framework                 | Methodology (PBL, BSC, OKR, ABNT)                       |
+| Database                  | Data repository (spreadsheet, CMS, source library)      |
+| External API              | Official source / stakeholder / vendor                  |
+| Code rules                | Quality protocols                                       |
+| Code style                | Tone of voice / formatting                              |
+| Test suite                | Validation criteria                                     |
+| CI/CD                     | Review / approval pipeline                              |
+| Lint hook                 | Automated checklist                                     |
+| Blocking hook             | Pre-publication validation                              |
+| Branches/commits          | Versions / revisions                                    |
+| PR review                 | Peer review                                             |
+| Bug                       | Inconsistency / factual error                           |
+| Refactoring               | Reorganization / clarification                          |
+| Deploy                    | Publication / delivery                                  |
+| Production                | Final environment / client                              |
+
+---
+
+## Application by Project Type
+
+### Academic Research
+
+```text
+.ai/
+├── INSTRUCTIONS.md          (research question, methodology, deadline)
+├── skills/
+│   ├── methodology/         (which method, why)
+│   ├── data-collection/     (sources, how to access, how to process)
+│   ├── analysis/            (techniques, formulas, software)
+│   ├── academic-writing/    (structure, citations, tone)
+│   └── review/              (validation checklist)
+├── rules/  (renamed protocols/)
+│   ├── citations-apa.md
+│   ├── paper-structure.md
+│   └── reproducibility.md
+└── docs/
+    ├── glossary.md          (domain technical terms)
+    ├── sources.md           (annotated bibliography)
+    ├── STATE.md             (methodological decisions, collected data, gaps)
+```
+
+**Applicable hooks:**
+- ✅ Destructive blocking (universal)
+- ✅ Citation validation before export
+- ❌ Code linting (does not apply)
+
+---
+
+### Content / Marketing / Technical Docs
+
+```text
+.ai/
+├── INSTRUCTIONS.md          (audience, channels, calendar)
+├── skills/
+│   ├── tone-of-voice/       (examples, words to avoid)
+│   ├── article-structure/   (intro, body, closing; lengths)
+│   ├── seo/                 (keywords, meta, structure)
+│   ├── fact-checking/       (reliable sources, process)
+│   └── editorial/           (review, approvals)
+├── rules/
+│   ├── style-guide.md       (capitalization, formatting, lists)
+│   └── compliance.md        (GDPR, regulated claims, disclaimers)
+└── docs/
+    ├── glossary.md
+    ├── personas.md
+    ├── STATE.md             (editorial calendar, drafts, under review)
+```
+
+**Applicable hooks:**
+- ✅ Destructive blocking
+- ✅ Spell check / markdown lint
+- ✅ Broken link validation
+- ❌ Test runner (does not apply)
+
+---
+
+### Business / Management
+
+```text
+.ai/
+├── INSTRUCTIONS.md          (objective, stakeholders, adopted frameworks)
+├── skills/
+│   ├── executive-report/    (structure, audience, level)
+│   ├── swot-analysis/       (template, guiding questions)
+│   ├── okrs/                (definition, tracking, review)
+│   ├── presentation-deck/   (visual principles, narrative)
+│   └── financial-analysis/  (P&L, indicators, projections)
+├── rules/
+│   ├── tone-for-board.md
+│   └── confidentiality.md
+└── docs/
+    ├── glossary.md          (business terms)
+    ├── stakeholders.md      (map, expectations)
+    ├── STATE.md             (deals in progress, quarterly OKRs)
+```
+
+---
+
+### Legal / Compliance
+
+```text
+.ai/
+├── INSTRUCTIONS.md          (jurisdiction, areas, critical risks)
+├── skills/
+│   ├── contract-drafting/   (clauses, standards)
+│   ├── clause-analysis/     (risks, ambiguities)
+│   ├── gdpr-compliance/     (DPIA, legal basis, rights)
+│   └── legal-opinions/      (structure, legal reasoning)
+├── rules/
+│   ├── legal-language.md
+│   ├── case-law-citation.md
+│   └── confidentiality.md   (critical rule for LLMs)
+└── docs/
+    ├── glossary.md
+    ├── case-law.md          (relevant precedents)
+    ├── STATE.md             (active cases, deadlines)
+```
+
+**Especially relevant hooks:**
+- ✅ Block accidental disclosure of confidential information
+- ✅ Legal citation validation before export
+
+---
+
+### Educational
+
+```text
+.ai/
+├── INSTRUCTIONS.md          (audience, level, methodology, curriculum if K-12)
+├── skills/
+│   ├── instructional-design/ (Bloom, ADDIE, models)
+│   ├── lesson-plan/          (structure, objectives, activities)
+│   ├── assessment/           (questions, rubrics, validation)
+│   └── language-level/       (adapt for age/knowledge)
+├── rules/
+│   ├── inclusion-accessibility.md
+│   └── pedagogical-standard.md
+└── docs/
+    ├── student-personas.md
+    └── STATE.md
+```
+
+---
+
+## When NOT to Use the Framework
+
+Regardless of type:
+
+- **Disposable work** (1 day, no continuity) — overhead > gain
+- **Solo + 1 tool + 1 session** — a monolithic `CLAUDE.md` is sufficient
+- **No expectation of evolution** — memory and specs lose their purpose
+- **Purely creative domain without standards** (e.g., free art) — constraints get in the way
+
+**Use when:**
+- 3+ people (humans or agents) share the work
+- More than one IDE/tool is involved
+- Domain has rules, norms, or standards that must be respected
+- Continuity between sessions matters (weeks or months)
+- There is real cost to inconsistency (compliance, brand, quality)
+
+---
+
+## Common Adaptations
+
+### Folder substitutions
+
+| Traditional                    | Universal alternative                              |
+| ------------------------------ | -------------------------------------------------- |
+| `.ai/rules/`                   | `.ai/protocols/`                                   |
+| `.ai/docs/architecture.md`     | `.ai/docs/components.md`                           |
+| `.ai/docs/database-schema.md`  | `.ai/docs/data-model.md` or `.ai/docs/sources.md`  |
+| `setup-ide-links.sh`           | keep the name — still relevant                     |
+
+### Hooks that always apply
+
+- **Destructive command blocking** — universal
+- **Versioning `settings.json`** in git — universal
+
+### Domain-dependent hooks
+
+- Lint/format → exists for markdown, spreadsheets (validators), CSS, JSON, YAML — adapt to the output format
+- Test runner → exists as "output validator" for any artifact (link checker, schema validator, fact-checker)
+
+---
+
+## Final Principle
+
+The **Spec** layer describes **what the domain is**.
+The **Harness** layer ensures **consistent behavior** regardless of domain.
+The **Memory** layer preserves **continuity** regardless of domain.
+
+The three concepts do not depend on programming — they depend on any human activity with **structured knowledge**, **repeatable standards**, and **continuity over time**. The framework is universal because these three properties are universal.

package/templates/settings.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Read(**)",
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(rg:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(sudo:*)",
+      "Read(.env)",
+      "Read(.env.*)"
+    ],
+    "ask": [
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Write(**)"
+    ]
+  }
+}

package/templates/setup-ide-links.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# setup-ide-links.sh — Idempotent multi-IDE symlink installer for AXIS.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+if [ ! -d .ai ]; then
+  echo "error: .ai/ not found — run from project root" >&2
+  exit 1
+fi
+
+ln -sf .ai/INSTRUCTIONS.md AGENTS.md
+ln -sf .ai/INSTRUCTIONS.md CLAUDE.md
+
+mkdir -p .claude
+ln -sf ../.ai/INSTRUCTIONS.md .claude/CLAUDE.md
+ln -sf ../.ai/skills          .claude/skills
+[ -d .ai/rules ] && ln -sf ../.ai/rules .claude/rules || true
+
+mkdir -p .cursor
+ln -sf ../.ai/skills .cursor/skills
+[ -d .ai/rules ] && ln -sf ../.ai/rules .cursor/rules || true
+
+mkdir -p .agents
+ln -sf ../.ai/INSTRUCTIONS.md .agents/AGENTS.md
+ln -sf ../.ai/skills          .agents/skills
+[ -d .ai/rules ] && ln -sf ../.ai/rules .agents/rules || true
+
+mkdir -p .github
+ln -sf ../.ai/INSTRUCTIONS.md .github/copilot-instructions.md
+ln -sf ../.ai/skills          .github/skills
+[ -d .ai/rules ] && ln -sf ../.ai/rules .github/instructions || true
+
+echo "✓ symlinks installed"

package/templates/skills/abstraction-first.md

@@ -0,0 +1,55 @@
+---
+name: abstraction-first
+description: Design skill — forces clarity on objects, responsibilities, and boundaries
+  before any code is generated. Use before writing a REASONS Canvas, before starting
+  a feature with >2 interacting components, or when AI output shows structural drift
+  (duplicated logic, unclear ownership, inconsistent interfaces). Trigger terms:
+  design first, abstraction, domain model, OO design, layer boundaries, responsibility.
+---
+
+# Abstraction First
+
+Establish object design and layer boundaries before generating code. Without this, AI sprints on implementation while the structure falls apart.
+
+## When to Use
+
+- Feature introduces a new domain concept or entity
+- >2 components interact in the change
+- AI output shows structural drift (duplicated logic, unclear ownership)
+
+## Design Questions (answer before Canvas O section)
+
+1. **What objects exist?** One noun = one responsibility.
+2. **How do they collaborate?** A calls B to get X, B asks C for Y.
+3. **Where are the layer boundaries?** What does each layer own? What can it NOT do?
+4. **What varies independently?** → Strategy / Factory / interface.
+5. **What stays the same?** → Canvas Safeguards.
+
+## Layer Boundary Rules
+
+| Layer | Owns | Must NOT |
+| ----- | ---- | -------- |
+| Controller | Input parsing, routing | Business logic |
+| Service | Business rules, orchestration | DB queries, HTTP calls |
+| Repository | Data access | Business logic |
+| Domain/Entity | State + invariants | Infrastructure |
+
+## Output (feed into Canvas E + A + S)
+
+```markdown
+### Entities
+- <EntityA>: <single responsibility>
+### Collaboration
+- <ServiceA> delegates to <RepositoryA>; dispatches to <CalculatorA|B> via Strategy
+### Variation Points
+- Pricing varies by plan → Strategy pattern, interface: `PricingStrategy`
+### Invariants (→ Safeguards)
+- Bill total is always non-negative
+```
+
+## Final Validation
+
+- [ ] Every entity has a single stated responsibility
+- [ ] No circular layer dependencies
+- [ ] Variation points mapped to a named pattern
+- [ ] Invariants listed and will appear as Canvas Safeguards

package/templates/skills/alignment.md

@@ -0,0 +1,53 @@
+---
+name: alignment
+description: Intent-locking skill — makes "what we will do / what we won't do" explicit
+  and gets agreement on standards and constraints before implementation starts. Use
+  before writing the O section of a REASONS Canvas, before pairing with AI on a
+  complex task, or when PO and dev need to close the loop before a sprint. Trigger
+  terms: alignment, intent, scope, definition of done, constraints, agree before coding.
+---
+
+# Alignment
+
+Lock intent, scope, and constraints before generating code. Fast output with wrong intent produces slow rework.
+
+## When to Use
+
+- About to generate code for a feature with business rules
+- PO/BA/dev haven't explicitly agreed on scope boundaries
+- Prior AI session drifted from original intent
+- Canvas O (Operations) section is about to be written
+
+## Three Alignment Dimensions
+
+**1. Core Logic** — business rules as 1-sentence invariants:
+```
+- Standard plan: usage within quota is free; overage billed at model-specific rate
+- Routing: plan type determines formula; must be extensible
+```
+
+**2. Scope Boundaries** — explicit in/out:
+```
+In: calculate current bill, support standard + premium plans
+Out: customer CRUD, historical queries, subscription management
+```
+
+**3. Definition of Done** — concrete scenarios with numbers:
+```
+- 90K used of 100K quota + 30K tokens → 20K overage billed
+- Missing field → HTTP 400; unknown entity → HTTP 404
+```
+
+## Alignment Checklist
+
+- [ ] Core logic stated as testable invariants (not as code)
+- [ ] Scope out is explicit — "we will NOT" list agreed by all parties
+- [ ] DoD has ≥2 concrete scenarios with numeric expected values
+- [ ] Canvas N + S reviewed and agreed
+- [ ] No "TBD" in any section before generating code
+
+## Final Validation
+
+- [ ] All three dimensions documented and agreed
+- [ ] No open questions remain
+- [ ] Canvas R and O have enough detail to generate code

package/templates/skills/iterative-review.md

@@ -0,0 +1,55 @@
+---
+name: iterative-review
+description: Review skill — turns AI code output into a controlled engineering loop
+  instead of a one-shot draft. Use after AI generates code, when a code review reveals
+  issues beyond style, or when the team is stuck in "regenerate until it works" loops.
+  Covers the two-track review strategy: logic corrections (spec → code) vs. refactoring
+  (code → spec). Trigger terms: code review, AI output review, fix and iterate,
+  rework loop, review strategy, logic correction, refactoring sync.
+---
+
+# Iterative Review
+
+Turn AI output into a controlled engineering loop. Without a disciplined review-and-iterate cycle, teams either patch endlessly (solution drifts) or restart repeatedly (cost explodes).
+
+## When to Use
+
+- AI just generated code from a Canvas
+- Code review reveals structural or logic issues
+- Team is stuck in a "keep regenerating" loop
+
+## Review Priority Order
+
+1. **Architecture** — correct layer structure?
+2. **Business logic** — matches Canvas ACs?
+3. **Scope** — diff confined to Canvas Structure?
+4. **Code quality** — magic numbers, naming, duplication
+
+## Two Tracks for Issues
+
+**Track A — Logic Correction** (behavior changes) → direction: **spec → code**
+1. Identify mismatch between code and Canvas
+2. Update Canvas (R, O, or S section) with correct intent
+3. Regenerate only the affected Operations
+4. Verify only the targeted area changed
+
+> Never patch code for a logic issue without updating the spec first.
+
+**Track B — Refactoring** (no behavior change) → direction: **code → spec**
+1. Refactor code in small incremental steps
+2. Verify tests still pass
+3. Sync Canvas Operations/Structure to reflect the new structure
+
+## Iteration Checklist
+
+- [ ] Architecture check — no layer violations
+- [ ] All Canvas ACs verified with concrete values
+- [ ] Scope check — diff only touches files in Canvas Structure
+- [ ] Logic issues: Canvas updated before code patched
+- [ ] Refactoring: tests green, Canvas synced after
+
+## Final Validation
+
+- [ ] Canvas is accurate record of current code behavior
+- [ ] Tests cover all Canvas Safeguards
+- [ ] STATE.md updated with any new patterns or decisions

package/templates/skills/story-decompose.md

@@ -0,0 +1,54 @@
+---
+name: story-decompose
+description: Decomposes large requirements into independent, deliverable user stories
+  following the INVEST principle (1-5 days of work each). Use when a feature is too
+  large to spec in one pass, when requirements come as a blob of business text, or
+  when a PO/BA needs to align with a dev before implementation. Trigger terms:
+  user story, INVEST, story split, requirement decomposition, acceptance criteria.
+---
+
+# Story Decompose
+
+Breaks a large requirement into INVEST stories with concrete Given/When/Then ACs, ready for domain analysis or REASONS Canvas.
+
+## When to Use
+
+- Feature covers >2 user types, plans, or behavior variants
+- Estimated at >5 days of work
+- ACs are missing, vague, or written as technical tasks
+
+## INVEST Checklist (per story)
+
+| Letter | Test |
+| ------ | ---- |
+| **I** ndependent | Deliverable without another story done first? |
+| **N** egotiable | Details adjustable without losing core value? |
+| **V** aluable | Visible business value on its own? |
+| **E** stimable | Fits a rough effort estimate? |
+| **S** mall | 1-5 days of work? |
+| **T** estable | Has verifiable ACs? |
+
+## Story Template
+
+```markdown
+## Story <ID> — <Short title>
+**Background:** <Why this story matters — 1 sentence>
+**Scope in:** <What is included>
+**Scope out:** <Explicit exclusions>
+**Acceptance Criteria:**
+- Given <context>, When <action>, Then <expected with concrete values>
+```
+
+## Process
+
+1. Read full requirement; identify vertical slices (by user type, plan, or behavior)
+2. Draft one story per slice
+3. Apply INVEST checklist; split any story that fails S or T
+4. Present with IDs; confirm with user before advancing to Domain Analysis
+
+## Final Validation
+
+- [ ] Every story passes INVEST (S and T non-negotiable)
+- [ ] No cross-story dependencies
+- [ ] Each story has ≥2 ACs with concrete numeric values
+- [ ] Stories cover 100% of original scope