Feature/example

.github/copilot-instructions.md

@@ -0,0 +1,121 @@
+# Agent Kit — LLM Context
+
+This repository **is** the Agent Kit framework. It is not a project built with the framework — it is the framework itself.
+
+## What this repository contains
+
+Agent Kit is a process framework for LLM-assisted software development. It provides a structured process (lenses, gates, artifacts) and a learning mechanism (domain profiles) that accumulates knowledge across projects.
+
+When someone copies `framework/` into their own repository and points `AGENTS.md` at `BUILDER.md`, any LLM can follow the process to build software with verification and domain-specific knowledge.
+
+## Repository structure
+
+```
+.
+├── AGENTS.md                    # Example entry point (5 lines, points to BUILDER.md)
+├── README.md                    # Explanation: what the framework is and why it exists
+├── GUIDE.md                     # Tutorial: step-by-step first project walkthrough
+├── LICENSE                      # MIT
+│
+├── framework/                   # THE FRAMEWORK (this is what gets copied to target repos)
+│   ├── BUILDER.md               # Process contract — the LLM reads and follows this
+│   ├── GATEKEEPER.md            # Verification agent — executes commands, enforces gates
+│   ├── README.md                # Technical reference — gates, artifacts, contracts
+│   ├── VERSION                  # Framework version for tracking updates
+│   ├── domains/
+│   │   ├── _template.md         # Template for creating profile links that extend catalog profiles
+│   │   └── README.md            # How domain profiles work
+│   └── templates/
+│       ├── INTENT.md            # Template: what and why
+│       ├── DESIGN.md            # Template: how (architecture, decisions, risks)
+│       ├── VERIFICATION_LOG-template.md  # Template: proof (gate output, progress)
+│       └── DOMAIN_PROFILE-template.md    # Template: standalone full domain profile
+│
+├── catalog/                     # Community-contributed base profiles
+│   ├── README.md                # How to use and contribute profiles
+│   ├── apps-sdk-mcp-lit-vite.md # Real profile (11 pitfalls, 7 adversary Qs)
+│   └── web-kinu-preact-vite.md  # Real profile (4 pitfalls, 4 adversary Qs)
+│
+├── examples/                    # Real project artifacts showing the framework in action
+│   ├── mcp-task-widget/         # Complete example with intent, design, verification
+│   ├── logistics-control-tower/ # Full-sized project prompt
+│   └── test-habit-tracker/      # Spanish-language prompt example
+│
+└── docs/                        # Would hold generated artifacts in a real project
+```
+
+## Framework concepts
+
+- **Domain profiles** accumulate stack knowledge (pitfalls, adversary questions, checks, decisions) across projects
+- **Gates** (0-4) are verification checkpoints with real command output — "assumed to pass" is never valid
+- **Four lenses**: User, Architecture, Adversary, Domain — thinking modes, not sequential phases
+- **Anti-Loop Rule**: produce the Intent document before continuing to investigate
+- **Pre-Implementation Checkpoint**: 4 questions before writing any code
+- **Resume**: verification log Progress section enables continuing interrupted work
+
+### The process (BUILDER.md)
+
+The LLM determines project size (Quick / Standard / Full), then follows a structured process:
+
+1. **Intent** — Capture what and why before doing anything (`docs/[project]-intent.md`)
+2. **Domain profile** — Load accumulated stack knowledge, read every pitfall and adversary question
+3. **Skills** — Load relevant skills from `.github/skills/` and `.agents/skills/` as design guidance
+4. **Design** — Architecture, decisions, risks, pitfalls applied, adversary questions answered (`docs/[project]-design.md`)
+5. **Pre-Implementation Checkpoint** — 4 mental questions before writing code
+6. **Gated build** — Gates 0-4 with real command output recorded
+7. **Self-review** — Adversary lens + domain checklist
+8. **Domain learning** — Update the profile with new discoveries
+
+### Domain profiles (the differentiator)
+
+Domain profiles use an **inheritance model**. Base profiles in `catalog/` contain stack-wide knowledge (pitfalls, adversary questions, automated checks, decision history). Profile links in `framework/domains/` extend a base profile with project-specific additions. Every gate failure becomes a new pitfall. Every project makes the next one better.
+
+Community-contributed base profiles live in `catalog/`. Create a profile link in `framework/domains/` that extends the relevant catalog profile — see `framework/domains/_template.md` for the format.
+
+A base profile contains: Selection Metadata, Terminology Mapping, Verification Commands, Common Pitfalls, Adversary Questions, Integration Rules, Automated Checks, Decision History, Review Checklist. A profile link contains: `extends` reference, Local Pitfalls, Local Overrides, Local Decision History.
+
+### Verification gates
+
+Gates are mandatory checkpoints with real command output. "Assumed to pass" is never valid. Gates 0 (deps) → 1 (scaffold) → 2 (features) → 3 (tests) → 4 (clean build).
+
+### Artifacts
+
+- **Intent** — Scope anchor. Given/when/then behaviors, MUST/MUST NOT constraints, IN/OUT scope.
+- **Design** — Single document replacing PRD + tech spec + implementation plan. Includes Adversary Questions Applied and Domain Pitfalls Applied as separate mandatory sections.
+- **Verification Log** — Gate evidence + Progress section for resuming interrupted work.
+
+### Anti-Loop Rule
+
+The LLM produces the Intent before continuing to investigate. Unclear decisions become open questions asked to the human — not reasons to keep researching.
+
+### Resume mechanism
+
+Each verification log has a Progress table at the top. When a session is interrupted, the next session reads Progress and continues from the last completed step.
+
+## Documentation follows Diátaxis
+
+| Document | Type | Serves |
+|----------|------|--------|
+| `README.md` | Explanation | Understanding — what and why |
+| `GUIDE.md` | Tutorial | Learning — step-by-step first project |
+| `framework/README.md` | Reference | Information — specs, contracts, definitions |
+| `BUILDER.md` | Reference | Information — the process contract (for LLMs) |
+| `GATEKEEPER.md` | Reference | Information — the verification contract (for LLMs) |
+
+## When modifying the framework
+
+- `BUILDER.md` is the source of truth for the process. Changes here affect how every LLM behaves.
+- Profile link template (`framework/domains/_template.md`) defines what new profile links look like. Full profile template (`framework/templates/DOMAIN_PROFILE-template.md`) defines standalone profiles and catalog contributions. Changes propagate to all future profiles.
+- Template changes (`templates/*.md`) affect artifact structure for all future projects.
+- `README.md`, `GUIDE.md`, and `framework/README.md` must stay aligned with `BUILDER.md`. If the process changes, the docs must reflect it.
+- Examples in `examples/` are historical artifacts — do not modify them to match framework changes.
+- Catalog profiles in `catalog/` are contributed by the community — review for quality but preserve the contributor's learnings.
+
+## Conventions
+
+- All framework documentation is in English.
+- Standalone/base profiles use the structure in `framework/templates/DOMAIN_PROFILE-template.md`. Profile links use `framework/domains/_template.md`. Do not deviate.
+- Verification logs are per-project: `docs/[project]-verification.md`, not a shared file.
+- Project code goes in its own directory, never at the repo root.
+- The AGENTS.md entry point is intentionally minimal (5 lines). Process logic lives in BUILDER.md.
+- Skills are guidance, not process. They live in `.github/skills/` (repo-level) or `.agents/skills/` (agent-level/external). Skills cannot override gates, skip artifacts, or replace domain profile correctness. Technical learnings go in domain profiles; process learnings go in skills; project-specific learnings go in `docs/`.

AGENTS.md

@@ -1,5 +1,7 @@
 # Agent Instructions
 
-Read and follow `agent-kit/BUILDER.md` for all tasks.
+The framework operates on a strict **Adversarial Verification Loop**:
+- For design, planning, and code implementation tasks: Read and follow `framework/BUILDER.md`.
+- For execution, testing, and mechanical verification tasks: Read and follow `framework/GATEKEEPER.md`.
 
 Project artifacts (intent, design, verification) go in `docs/`.

GUIDE.md

@@ -10,27 +10,37 @@ In this tutorial, we will set up Agent Kit in a new repository and use it to bui
 
 ## Step 1: Copy the framework into your repo
 
-Copy three things into your repository's root:
+Copy the framework into your repository's root:
 
 ```bash
-cp -R agent-kit/ your-repo/agent-kit/
+cp -R framework/ your-repo/framework/
 cp AGENTS.md your-repo/
 mkdir -p your-repo/docs
+
+# Optional: if a catalog profile exists for your stack, copy it too
+mkdir -p your-repo/catalog
+cp catalog/[your-profile].md your-repo/catalog/
 ```
 
 Your repo should now look like this:
 
 ```
 your-repo/
 ├── AGENTS.md
-├── agent-kit/
+├── framework/
 │   ├── BUILDER.md
+│   ├── GATEKEEPER.md
+│   ├── README.md
+│   ├── VERSION
 │   ├── domains/
 │   │   └── _template.md
 │   └── templates/
 │       ├── INTENT.md
 │       ├── DESIGN.md
-│       └── VERIFICATION_LOG-template.md
+│       ├── VERIFICATION_LOG-template.md
+│       └── DOMAIN_PROFILE-template.md
+├── catalog/                         ← only if you copied a profile
+│   └── [your-profile].md
 └── docs/
 ```
 
@@ -39,12 +49,14 @@ Open `AGENTS.md` and verify it contains:
 ```markdown
 # Agent Instructions
 
-Read and follow `agent-kit/BUILDER.md` for all tasks.
+The framework operates on a strict Adversarial Verification Loop:
+- For design, planning, and code implementation tasks: Read and follow `framework/BUILDER.md`.
+- For execution, testing, and mechanical verification tasks: Read and follow `framework/GATEKEEPER.md`.
 
 Project artifacts (intent, design, verification) go in `docs/`.
 ```
 
-That's all `AGENTS.md` needs. The process logic lives in `BUILDER.md`.
+That's all `AGENTS.md` needs. The Builder handles design and implementation; the GateKeeper handles verification. The process logic lives in their respective files.
 
 ## Step 2: Write your prompt
 
@@ -96,15 +108,24 @@ This is your chance to course-correct. If a decision is wrong, say so now. If a
 
 ## Step 5: Watch the domain profile load (or get created)
 
-If a domain profile exists for your stack in `agent-kit/domains/`, the LLM loads it and reads every pitfall and adversary question before continuing.
+If a matching base profile exists in `catalog/`, the LLM creates a **profile link** in `framework/domains/` with `extends: [profile-id]` and reads every pitfall and adversary question from the base before continuing. The link template is `framework/domains/_template.md`.
+
+If no base profile exists, the LLM creates a **standalone full profile** directly in `framework/domains/` using `framework/templates/DOMAIN_PROFILE-template.md`. The first version will be minimal — terminology mapping, verification commands, a couple of pitfalls. It will grow as the project discovers new pitfalls. When you want to reuse it across projects, move it to `catalog/` and replace it with a link.
+
+## Step 6: Skills get loaded (if they exist)
 
-If no profile exists, the LLM creates one from `agent-kit/domains/_template.md`. The first version will be minimal — terminology mapping, verification commands, a couple of pitfalls. That's fine. It will grow.
+If your repo has skills installed in `.github/skills/` or `.agents/skills/`, the LLM scans their descriptions and loads any that match the task. For example, a `frontend-design` skill would be loaded for a UI task but ignored for a backend API.
 
-## Step 6: Review the Design
+Skills provide design guidance — aesthetic direction, API conventions, documentation style — but they don't replace the domain profile or the verification gates. You might not have any skills yet, and that's fine. The framework works without them.
+
+> **Tip:** You can install community skills from [skills.sh](https://skills.sh) (`npx skills add owner/skill-name`) or create your own in `.github/skills/your-skill/SKILL.md`.
+
+## Step 7: Review the Design
 
 The LLM creates `docs/[project]-design.md`. This is one document that replaces a separate PRD, tech spec, and implementation plan. You will see:
 
 - **Domain Profile Selection** — which profile was chosen and why (with scores)
+- **Skills Loaded** — which skills were loaded (or "none")
 - **Stack** — technologies with verified versions
 - **Architecture** — structure, data flow, initialization chain
 - **Decisions** — every architectural choice with rationale
@@ -114,7 +135,7 @@ The LLM creates `docs/[project]-design.md`. This is one document that replaces a
 
 The Adversary Questions and Domain Pitfalls sections are where the domain profile earns its value. They force the LLM to confront known failure modes *before* writing a single line of code.
 
-## Step 7: Watch the gated build
+## Step 8: Watch the gated build
 
 Now the LLM starts building. It proceeds through gates:
 
@@ -135,14 +156,15 @@ If a gate fails, the LLM:
 
 This last step is the learning cycle in action. A failure today becomes a prevention for tomorrow.
 
-## Step 8: Check the verification log
+## Step 9: Check the verification log
 
 When the build is complete, open `docs/[project]-verification.md`. At the top you will see the Progress table:
 
 ```markdown
 | Step | Status |
 |------|--------|
 | Intent | PASS |
+| Skills loaded | PASS |
 | Design | PASS |
 | Gate 0: Dependencies | PASS |
 | Gate 1: Scaffold | PASS |
@@ -157,18 +179,23 @@ Below that: real output for every gate, a failure history (if anything failed al
 
 If Gate 4 passed, the project builds and tests from a clean state. That's the proof.
 
-## Step 9: Check the domain profile
+## Step 10: Check what the LLM learned
+
+After the project, check two places:
 
-Open `agent-kit/domains/[your-profile].md`. Compare it to how it looked before the project. You may see:
+**Your profile link** (`framework/domains/[your-profile].md`) — project-specific discoveries:
+- New **Local Pitfalls** — things unique to this project's context
+- New **Local Decision History** — constraints specific to this project
 
-- New entries in **Common Pitfalls** — things the LLM discovered during implementation
+**The base profile** (`catalog/[profile-id].md`) — stack-wide discoveries:
+- New entries in **Common Pitfalls** — things any project on this stack should know
 - New **Adversary Questions** — traps specific to this stack
 - New **Decision History** entries — constraints learned the hard way
 - Updated **Automated Checks** — new detection patterns
 
-This is the flywheel. The next project on this stack will load this profile and avoid the problems this project discovered.
+This is the flywheel. The next project on this stack inherits the updated base profile automatically through `extends`. Local pitfalls that prove useful across projects should be contributed back to the catalog profile.
 
-## Step 10: Resume interrupted work (when it happens)
+## Step 11: Resume interrupted work (when it happens)
 
 Sessions get interrupted — context limits, network issues, or just closing the chat. When you come back, start a new session and prompt:
 
@@ -184,8 +211,8 @@ The LLM reads the verification log's Progress section, finds the last completed
 
 **Add constraints as you discover preferences.** Every time you say "always do X" or "never do Y", the framework captures it — in the Intent for this project, in the domain profile for all future projects on this stack.
 
-**Bring profiles to new repos.** When you start a new repository with the same stack, copy the domain profile along with `agent-kit/`. All accumulated knowledge travels with it.
+**Bring profiles to new repos.** When you start a new repository with the same stack, copy `framework/` and include the relevant base profiles from `catalog/`. Create a new profile link in `framework/domains/` that extends the base. All accumulated stack knowledge travels with it; project-specific knowledge stays behind.
 
-For the full technical reference — file descriptions, gate definitions, domain profile contract, and artifact specs — see [`agent-kit/README.md`](agent-kit/README.md).
+For the full technical reference — file descriptions, gate definitions, domain profile contract, and artifact specs — see [`framework/README.md`](framework/README.md).
 
 For the concepts behind the framework — why it works, how the learning cycle operates, what makes domain profiles different — see the [project README](README.md).