AI Assistant Dot Files — Context Engineering Framework

One canonical set of agents, skills, and rules — written once in shared/, generated or symlinked into whatever AI coding tool you actually use (Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini Antigravity, OpenAI/Codex, JetBrains AI Assistant + Junie, Roo Code, Cline). Edit shared/, run one script, every tool stays in sync — no more hand-copying the same instructions into five different config formats.

This also ships a full multi-agent feature delivery pipeline (spec → analysis → architecture → implementation → review → security → QA → docs → deploy) built around Clean Architecture, TDD, and the craftsmanship principles of Robert C. Martin, Martin Fowler, Kent Beck, and Neal Ford.

For deeper detail beyond this README:

• docs/ARCHITECTURE.md — the shared/ layer design, tier system, context flow
• docs/AGENT_REFERENCE.md — every agent's role and what actually checks its work today
• docs/CONTRIBUTING.md — how to add a new agent, skill, rule, or platform
• docs/runbooks/ — operational guides, including adding a platform and editing agent prompts
• docs/MIGRATION.md — upgrading a pre-restructure ("v1") checkout to the canonical shared/ layer ("v2")

flowchart LR
    You(["You"]) -- "edit once" --> Shared["shared/\nagents + skills + rules"]

    Shared -- generate-configs.sh --> Tools["Claude Code, Cursor, Windsurf,\nGitHub Copilot, Gemini/Antigravity,\nOpenAI/Codex, JetBrains+Junie, Roo Code, Cline"]

    Tools --> Pipeline[["deliver-feature\n14-agent delivery pipeline"]]
    Pipeline --> CML[["Context + Memory + Learning\n(gets smarter every delivery)"]]
    CML -. "prompt/rule edits,\nnew Knowledge Items" .-> Shared

One canonical source, nine tools kept in sync automatically, one governed pipeline, and a feedback loop that improves the framework itself over time — see context-engineering.md for how the Context/Memory/Learning loop actually works, and the pipeline diagram further down for the full 14-agent sequence.

shared/                              <- single source of truth, edit here only
├── agents/        (39 agents)       <- .md with YAML frontmatter, versioned (CHANGELOG.md)
├── skills/        (69 skills)       <- .md with trigger keywords/patterns
├── rules/                           <- architecture-guardrails.md, design-principles.md, approval-gates.md
├── contracts/                       <- required-section contracts for pipeline agent handoffs
├── knowledge/                       <- portable Knowledge Items (KIs)
├── templates/                       <- tutorial/scaffold content, e.g. my-first-feature.md
├── ARCHITECTURE_RULES.md
├── DOMAIN_DICTIONARY.md
├── TEAM_TOPOLOGY.md               <- Bounded Context -> team/type/interaction-mode registry (Skelton & Pais)
├── memory-registry.json           <- catalog of every durable memory source + retrieval backend
├── platform-registry.json           <- tier/capability/format per platform
├── mcp/                             <- MCP server scaffold (6 M1 tools, stdio transport, Go)
└── mcp-patterns/go/                 <- copy-me templates; compile with build tags removed

        │  scripts/generate-configs.sh (reads shared/ + platform-registry.json)
        ▼

Generated / symlinked platform configs (this repo, or any target project via install.sh)
├── .claude/{agents,rules,skills}/    -> symlinks to shared/ (Tier 1: Full)
├── .cursor/rules/*.mdc               <- generated, rules inlined (Tier 2: Personas + Rules)
├── .windsurfrules                    <- generated, flat (Tier 2)
├── .github/copilot-instructions.md   <- generated (Tier 2), + .github/instructions/*.instructions.md
├── AGENTS.md                          <- generated (confirmed read by Gemini Antigravity)
├── .agents/{skills,rules}/            <- symlinks to shared/ (project installs; ~/.gemini/config/skills/ for --global)
└── .openai.md                        <- generated (Tier 3)

        │  install.sh --global | --project <path>
        ▼

Your machine (~/) or a target project — agents/skills/rules active in every AI tool you use

scripts/check-parity.sh verifies every generated config actually matches the canonical shared/ source — run it after any edit to shared/ before trusting the generated files are current.

git clone <this-repo> ai-assistant-dot-files
cd ai-assistant-dot-files

# See what would happen first, without touching anything
./install.sh --global --dry-run

# Install globally (symlinks shared/ into ~/.claude, ~/.cursor, etc. — always current after a git pull)
./install.sh --global

# Or install into one specific project (also symlinked by default -- see note below)
./install.sh --project /path/to/your-project

# Verify everything is wired correctly
scripts/check-parity.sh

Both --global and --project auto-detect which of the six platforms you actually have installed and only generate configs for those (--platform <name> to force a single one), and both symlink by default — a --project install still depends on this repo's checkout staying where it is, exactly like --global does. Pass --copy if you want a project install that's a real, independent copy instead (also required on Windows without WSL, where symlinks need elevated permissions). Add --tour to either mode to run the onboard skill walkthrough right after install.

Once installed:

# Claude Code: agents are native subagents, skills are slash commands
claude
> /new-feature "password reset via email"       # interview + spec
> /deliver-feature features/password-reset.md   # full pipeline

# Any other tool: agents are personas, invoke by @-tagging or referencing the file
> Act as the code-reviewer persona from shared/agents/code-reviewer.md and review my current changes.

Version marker — every non-dry-run install writes .claude/framework-install.json into the target (or ~/.claude/ for --global). It records the installed git tag, commit SHA, install date, mode (symlink/copy), and framework level. health-check.sh reads this marker when invoked from within an installed project and reports a WARN if the source repo has moved ahead — making drift from --copy installs visible without manual archaeology. Pre-v3.3 installs have no marker; the legacy forensic detection in docs/prompts/update-installed-framework.md remains the fallback.

To remove: ./uninstall.sh --global (or --project <path>) restores whatever was backed up during install (and removes the version marker).

Teams using this framework across multiple repositories can share Knowledge Items (KIs) via an organization-owned knowledge-hub git repo. See ADR-003 for the full design rationale.

Setup — create .claude/sync-config.yaml at the root of your framework checkout:

memory_sync:
  org_repo: git@github.com:<your-org>/knowledge-hub.git
  cache_dir: ~/.claude/sync-cache
  push_pr_base: main

Pull — diff org KIs into your local shared/knowledge/ (dry run first, then apply):

./install.sh --sync-memory               # preview changes
./install.sh --sync-memory pull --confirm  # apply

Push — promote mature .claude/knowledge/ KIs (>30 days old) to the org repo via PR:

./install.sh --sync-memory push             # preview candidates
./install.sh --sync-memory push --confirm   # open PR (requires gh CLI for GitHub)

Conflict rules: shared/knowledge/ → org repo wins on pull. .claude/knowledge/ → local always wins (project KIs are never overwritten). Name collisions between org and project KIs halt the pull until resolved manually.

Auth: SSH is primary. For enterprises where SSH is disabled, set MEMORY_SYNC_TOKEN=<pat> in the environment — the script converts the SSH URL to HTTPS automatically.

Full definitions of Agent, Persona, and Capability Tier live in DOMAIN_DICTIONARY.md. The short version: only Tier 1 has real multi-step agent orchestration with tool access; Tiers 2/3 get the same underlying knowledge as a persona — a context frame with no autonomous pipeline participation — because that's what those tools are actually capable of running.

Full definitions in shared/agents/; versions tracked in shared/agents/CHANGELOG.md. For what actually checks each agent's work today (a contract, a downstream reviewer, a human approval gate, or an honestly documented gap), see docs/AGENT_REFERENCE.md.

Full definitions in shared/skills/<name>/SKILL.md, including exact trigger keywords/intent patterns. Grouped by what they're for:

flowchart TD
    User([User]) --> SpecWriter[spec-writer]
    SpecWriter --> ContextEngineer[context-engineer]

    subgraph "Phase 1: Discovery & Design"
        ContextEngineer --> Analyst[analyst]
        Analyst --> Pause1{{"⏸ confirm scope"}}
        Pause1 --> Architect[architect]
        Architect -->|"RFC written"| Pause2{{"⏸ confirm architecture"}}
        Architect -.->|"no RFC"| Perf[performance-engineer]
        Pause2 --> Perf
        Perf --> Data[data-engineer]
    end

    subgraph "Phase 2: Implementation & Review"
        Data --> Developer[developer]
        Developer --> CodeReviewer[code-reviewer]
        CodeReviewer -. "CHANGES REQUESTED" .-> Developer
        CodeReviewer --> A11y[accessibility-engineer]
        A11y --> SecurityReviewer[security-reviewer]
        SecurityReviewer -->|"Critical finding"| Pause3{{"⏸ confirm fix"}}
        SecurityReviewer -.->|"no Critical finding"| QAEngineer
    end

    subgraph "Phase 3: Verification & Shipping"
        Pause3 --> QAEngineer[qa-engineer]
        QAEngineer --> SRE[sre-engineer]
        SRE --> TechWriter[tech-writer]
        TechWriter --> DevOpsEngineer[devops-engineer]
        DevOpsEngineer --> Pause4{{"⏸ confirm docs complete"}}
        Pause4 --> Ship{{"⏸ ship to Friday?"}}
    end

    classDef conditional stroke-dasharray: 5 5
    class Architect,Perf,Data,A11y,SecurityReviewer conditional

    classDef checkpoint fill:#fef3c7,stroke:#d97706,color:#78350f
    class Pause1,Pause2,Pause3,Pause4,Ship checkpoint

Dashed-border agents (architect, performance-engineer, data-engineer, accessibility-engineer, security-reviewer) are conditional — each runs only if its own trigger condition is met (a new pattern/abstraction, a performance SLA, a data model change, a UI surface, a security surface respectively); skipped otherwise, straight through to the next mandatory step. Amber nodes are real stops — the pipeline doesn't proceed past one without your explicit confirmation. Every arrow is also gated by validate-artifact (structural contract check) where the producing agent has a contract in shared/contracts/, and the whole run is checkpointed to .claude/feature-workspace/pipeline-state.json

• pipeline-trace.json so it can be resumed or rolled back (resume-pipeline) rather than restarted from scratch.

Claude Code (native support) — agents are real subagents with tool access:

claude
> /new-feature "user authentication"
> /deliver-feature features/user-authentication.md

Cursor / Windsurf — agents are personas; reference the file directly:

Act exactly as described in shared/agents/developer.md. Read .claude/feature-workspace/analysis.md
and implement the feature.

GitHub Copilot — same idea, tag the file:

Act as the Code Reviewer persona from #file:shared/agents/code-reviewer.md. Review my current
workspace changes against ARCHITECTURE_RULES.md.

Most skills don't require a full feature delivery — they work standalone against any file or directory:

> /design-review src/utils/payment-processor.ts
> /threat-model src/api/checkout.ts
> /complexity-check src/core/
> /chaos-experiment src/services/database.ts
> /refactor-to-pattern "Rewrite this switch statement as Strategy" src/parsers/document.ts

• TDD/BDD (Kent Beck): Red-Green-Refactor, tests drive design.
• Clean Code & SOLID (Uncle Bob): cyclomatic complexity < 7, functions < 30 LOC.
• Evolutionary Architecture (Neal Ford & Martin Fowler): high cohesion, loose coupling, named refactorings.
• YAGNI & KISS: no speculative abstraction.
• The Boy Scout Rule: leave touched files cleaner than you found them.
• Security & Observability: no hardcoded secrets, OTel by default, structured low-cardinality logging.

Full rules: shared/rules/architecture-guardrails.md, shared/rules/design-principles.md, shared/rules/approval-gates.md, ARCHITECTURE_RULES.md, DOMAIN_DICTIONARY.md.

Agent, skill, and Knowledge Item frontmatter blocks have JSON Schemas under shared/schemas/. Opting in gets you autocomplete and inline validation while authoring — for example, tools: WhatEverRandomName gets flagged in-editor instead of only at scripts/health-check.sh time (which today validates field presence only, not values).

VS Code — install the Red Hat YAML extension (redhat.vscode-yaml), then copy the template:

cp .vscode/settings.json.example .vscode/settings.json

Cursor — same setup, Cursor uses the same YAML language server:

cp .cursor/settings.json.example .cursor/settings.json

Both templates wire shared/schemas/agent-frontmatter.schema.json, skill-frontmatter.schema.json, and ki-frontmatter.schema.json to the matching glob patterns under shared/. The contracts these schemas encode live under shared/contracts/.

Dual-licensed by content type:

• Code (scripts/, install.sh, uninstall.sh) — MIT.
• Prompt/instructional content (shared/agents/, shared/skills/, shared/rules/, shared/knowledge/, docs/, top-level blueprint files) — CC BY 4.0.

If you copy or adapt an agent, skill, or rule from this repo, keep the attribution — see LICENSE-CONTENT.md for the exact wording. Every agent, skill, and rule file also carries this attribution at the bottom of the file itself, so it travels with the file if it's copied out on its own.