cairn-brain 0.2.1__tar.gz

cairn_brain-0.2.1/.cairn/config.toml

@@ -0,0 +1,35 @@
+# Cairn project configuration. Every key is optional; delete what you don't change.
+
+[server]
+port = 4747                      # first free port from here is used
+
+[context]
+budget = 1800                    # default token budget for agent-facing context packs
+
+[models]
+provider = "claude-code"         # auto | anthropic | openai | claude-code  (auto: API key, else your Claude Code login)
+fast = "claude-haiku-4-5-20251001"   # classification, summaries at volume
+balanced = "claude-sonnet-5"         # extraction, linking tie-breaks
+deep = "claude-opus-5-5"             # why / impact / drift synthesis, ask
+frontier = "claude-fable-5-1"        # opt-in whole-system reviews only
+# base_url = "http://localhost:11434/v1"
+
+[deep]
+enabled = "auto"                 # auto = on when a model key is present
+budget_tokens = 150000           # hard ceiling per deep sync
+graph_url = ""                   # falkor://host:6379 or bolt://host:7687 ; empty = embedded store
+
+[history]
+max_commits = 3000
+
+[sessions]
+project = ""                     # session-capture project name if it differs from the folder name
+
+[recall]
+worker_spawn = false
+
+[map]
+ignore = ["src/cairn/ui/mock/"]
+
+[temporal]
+backend = ""

cairn_brain-0.2.1/.claude/agents/cairn-architect.md

@@ -0,0 +1,12 @@
+---
+name: cairn-architect
+description: Design reviewer for plans and cross-cutting changes. Use for /cairn-plan reviews, refactors touching hubs, or when impact risk is HIGH.
+tools: Read, Grep, Glob, mcp__cairn__cairn_context, mcp__cairn__cairn_impact, mcp__cairn__cairn_why, mcp__cairn__cairn_specs, mcp__cairn__cairn_trace, mcp__cairn__cairn_recall
+model: opus
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Review the proposed design against the project's reality. Check: constitution principles, hub
+symbols it touches (`cairn_trace` explain), impact of each changed interface, past incidents in the
+area, conventions in memory, and conflicts with other open spec tasks. Output: verdict
+(approve / approve with changes / rethink), the 3 most important risks with evidence [ids], and
+concrete changes to the plan. Be decisive and brief.

cairn_brain-0.2.1/.claude/agents/cairn-implementer.md

@@ -0,0 +1,11 @@
+---
+name: cairn-implementer
+description: Implements one spec task end to end with the project's memory in context. Use for tasks from tasks.md, especially [P] tasks that can run in parallel.
+tools: Read, Edit, Write, Bash, Grep, Glob, mcp__cairn__cairn_context, mcp__cairn__cairn_impact, mcp__cairn__cairn_remember
+model: sonnet
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Implement exactly one task. Before touching a file, call `cairn_impact` on it and respect every
+convention and warning returned. Follow the task's file paths. Run the relevant tests. Mark the
+task `[x]` in tasks.md only when tests pass. If you discover a durable gotcha, record it with
+`cairn_remember`. Report: files changed, tests run, anything the reviewer should check.

cairn_brain-0.2.1/.claude/agents/cairn-reviewer.md

@@ -0,0 +1,11 @@
+---
+name: cairn-reviewer
+description: Reviews a diff against specs, history and conventions before merge. Use after implementation or before opening a PR.
+tools: Read, Grep, Glob, Bash, mcp__cairn__cairn_impact, mcp__cairn__cairn_specs, mcp__cairn__cairn_why, mcp__cairn__cairn_recall
+model: opus
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Run `git diff --stat` and `git diff` for the change under review. For each changed file call
+`cairn_impact`; call `cairn_specs` with drift=true for the active spec. Flag: requirement
+violations, untested dependents, co-changing files that were not updated, repeats of past
+incidents, and broken conventions. Output a prioritised list with [ids] and a merge verdict.

cairn_brain-0.2.1/.claude/agents/cairn-scout.md

@@ -0,0 +1,12 @@
+---
+name: cairn-scout
+description: Fast context gatherer. Use PROACTIVELY before non-trivial edits to collect impact, rationale, conventions and past work for the files involved. Returns a compact brief, never edits.
+tools: Read, Grep, Glob, mcp__cairn__cairn_context, mcp__cairn__cairn_impact, mcp__cairn__cairn_why, mcp__cairn__cairn_search, mcp__cairn__cairn_recall
+model: haiku
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+You gather evidence; you do not decide or edit. For the task you are given:
+1. Call `cairn_context` with the task. Identify the 1–3 concrete targets.
+2. For each target call `cairn_impact` (depth 1). Call `cairn_why` only if intent is unclear.
+3. Return at most 15 lines: targets, risk level, dependents/tests to re-run, co-changing files,
+   warnings, owning spec task, relevant conventions. Keep every [id]. No prose padding.

cairn_brain-0.2.1/.claude/commands/cairn/ask.md

@@ -0,0 +1,7 @@
+---
+description: Ask the project memory a question
+argument-hint: <question>
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Call `cairn_context` with task "$ARGUMENTS". Answer the question from that evidence, citing [ids].
+If you need more detail on a specific target, follow up with `cairn_why` or `cairn_impact`.

cairn_brain-0.2.1/.claude/commands/cairn/brief.md

@@ -0,0 +1,6 @@
+---
+description: Project briefing — structure, active spec, team knowledge, recent agent work
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Run `cairn brief` in the terminal and present it as a short orientation. Then suggest the two
+most useful next actions given the active spec and any drift findings.

cairn_brain-0.2.1/.claude/commands/cairn/drift.md

@@ -0,0 +1,8 @@
+---
+description: Check where the code has drifted from its specs
+argument-hint: [spec id]
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Call `cairn_specs` with spec "$ARGUMENTS" and drift=true. Group findings by severity. For each
+high finding, open the cited task or requirement and the file, confirm or dismiss it, and propose
+the smallest fix. Do not edit files until the user agrees.

cairn_brain-0.2.1/.claude/commands/cairn/impact.md

@@ -0,0 +1,8 @@
+---
+description: What breaks if this changes — dependents, co-change, past incidents, owners
+argument-hint: <file | symbol | Class.method>
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Call the `cairn_impact` tool with target "$ARGUMENTS". Summarise: risk level and why, the
+dependents and tests to re-run, files that usually change together, historical warnings, and the
+spec task that owns this code. End with a short checklist for making the change safely.

cairn_brain-0.2.1/.claude/commands/cairn/remember.md

@@ -0,0 +1,8 @@
+---
+description: Save a durable team learning (convention, decision, gotcha, preference, fact)
+argument-hint: <one-sentence learning>
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Rewrite "$ARGUMENTS" as one precise, self-contained sentence naming the code it applies to. Pick
+the kind: convention, decision, gotcha, preference or fact. Call `cairn_remember`. If it replaces
+an existing memory (check with `cairn_recall` first), pass `supersedes`.

cairn_brain-0.2.1/.claude/commands/cairn/why.md

@@ -0,0 +1,8 @@
+---
+description: Explain why a file or symbol is the way it is (rationale, origin, spec, decisions)
+argument-hint: <file | symbol | Class.method>
+---
+<!-- generated by cairn; safe to edit, removed by `cairn uninstall` -->
+Call the `cairn_why` tool with target "$ARGUMENTS". Then answer in at most 6 bullets: the original
+intent, the key decisions or constraints, and anything a developer must not break. Cite the
+[ids] from the tool output. If evidence is thin, say so rather than speculating.

cairn_brain-0.2.1/.claude/skills/cairn-analyze/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: "cairn-analyze"
+description: "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
+argument-hint: "Optional focus areas for analysis"
+compatibility: "Requires cairn project structure with .cairn/workflow/ directory"
+metadata:
+  author: "cairn"
+  source: "templates/commands/analyze.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before analysis)**:
+- Check if `.cairn/workflow/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_analyze` key
+- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that `.cairn/workflow/extensions.yml` could not be read (include the parser error) and that no hooks were checked, including any mandatory (`optional: false`) hooks registered there, then continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing command invocations from hook command names, replace dots (`.`) with hyphens (`-`). For example, `cairn.git.commit` → `/cairn-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Goal.
+    ```
+    After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:cairn-...` or `$cairn-...`). Emitting the block alone does not run the hook.
+- If no hooks are registered or `.cairn/workflow/extensions.yml` does not exist, skip silently
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/cairn-tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.cairn/workflow/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/cairn-analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.cairn/workflow/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.cairn/workflow/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/cairn-implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /cairn-specify with refinement", "Run /cairn-plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+### 9. Check for extension hooks
+
+After reporting, check if `.cairn/workflow/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_analyze` key
+- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that `.cairn/workflow/extensions.yml` could not be read (include the parser error) and that no hooks were checked, including any mandatory (`optional: false`) hooks registered there, then continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing command invocations from hook command names, replace dots (`.`) with hyphens (`-`). For example, `cairn.git.commit` → `/cairn-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+    After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:cairn-...` or `$cairn-...`). Emitting the block alone does not run the hook.
+- If no hooks are registered or `.cairn/workflow/extensions.yml` does not exist, skip silently
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS