From dd42507b1fb4558dc704a9582772f42cf31db5d1 Mon Sep 17 00:00:00 2001 From: Peter Bruinsma Date: Mon, 20 Apr 2026 14:30:47 +0000 Subject: [PATCH] chore(ai-framework): bump .ai to 32e7367; untrack generated adapters MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps .ai 90ef1ef → 32e7367, picking up: - fix(sync): anchor CWD to repo root (PR #8) - fix(sync): guard against wrong CWD instead of forcing cd (PR #9) — prevents stray .ai-repo/ and work/ scaffolds inside .ai/ when sync is invoked from the wrong CWD, without breaking the framework's test sandbox pattern. Embraces the framework's new track-vs-ignore convention: - Untrack .github/copilot-instructions.md, .github/skills/, .claude/rules/ai-framework.md — these are local build outputs regenerated by `bash .ai/sync.sh`. - Add them to .gitignore so they stop shadowing the canonical sources in .ai/ and .ai-repo/. - CLAUDE.md and .codex/instructions.md remain tracked (shared workspace context). Adds statusline artifacts from upstream PR #7: - .claude/settings.json — wires statusLine to .claude/statusline.sh - .claude/statusline.sh — framework-managed status line script Co-Authored-By: Claude Opus 4.7 (1M context) --- .ai | 2 +- .claude/rules/ai-framework.md | 200 ---------------- .claude/settings.json | 6 + .claude/statusline.sh | 87 +++++++ .codex/instructions.md | 8 +- .github/copilot-instructions.md | 206 ----------------- .github/skills/architect/SKILL.md | 53 ----- .github/skills/devcontainer/SKILL.md | 290 ------------------------ .github/skills/doc-gardening/SKILL.md | 101 --------- .github/skills/draft-spec/SKILL.md | 48 ---- .github/skills/patch/SKILL.md | 50 ---- .github/skills/plan-epic/SKILL.md | 51 ----- .github/skills/plan-milestones/SKILL.md | 44 ---- .github/skills/quality-score/SKILL.md | 68 ------ .github/skills/release/SKILL.md | 52 ----- .github/skills/review-code/SKILL.md | 54 ----- .github/skills/start-milestone/SKILL.md | 82 ------- .github/skills/tdd-cycle/SKILL.md | 62 ----- .github/skills/ui-debug/SKILL.md | 13 -- .github/skills/wrap-milestone/SKILL.md | 75 ------ .gitignore | 5 + 21 files changed, 103 insertions(+), 1454 deletions(-) delete mode 100644 .claude/rules/ai-framework.md create mode 100644 .claude/settings.json create mode 100755 .claude/statusline.sh delete mode 100644 .github/copilot-instructions.md delete mode 100644 .github/skills/architect/SKILL.md delete mode 100644 .github/skills/devcontainer/SKILL.md delete mode 100644 .github/skills/doc-gardening/SKILL.md delete mode 100644 .github/skills/draft-spec/SKILL.md delete mode 100644 .github/skills/patch/SKILL.md delete mode 100644 .github/skills/plan-epic/SKILL.md delete mode 100644 .github/skills/plan-milestones/SKILL.md delete mode 100644 .github/skills/quality-score/SKILL.md delete mode 100644 .github/skills/release/SKILL.md delete mode 100644 .github/skills/review-code/SKILL.md delete mode 100644 .github/skills/start-milestone/SKILL.md delete mode 100644 .github/skills/tdd-cycle/SKILL.md delete mode 100644 .github/skills/ui-debug/SKILL.md delete mode 100644 .github/skills/wrap-milestone/SKILL.md diff --git a/.ai b/.ai index 90ef1ef6..32e7367f 160000 --- a/.ai +++ b/.ai @@ -1 +1 @@ -Subproject commit 90ef1ef65a7c4a027a4296019540f5ac1e60f041 +Subproject commit 32e7367f4db80decfc6aff8b165dce88ad23d62c diff --git a/.claude/rules/ai-framework.md b/.claude/rules/ai-framework.md deleted file mode 100644 index de381e0a..00000000 --- a/.claude/rules/ai-framework.md +++ /dev/null @@ -1,200 +0,0 @@ -# AI Framework v2 - - -**Before starting any task**, read these files: -1. `.ai/rules.md` — Non-negotiable guardrails (full rules and enforcement levels) -2. `.ai/paths.md` — Artifact layout defaults -3. `.ai-repo/rules/` — Project-specific rules and conventions (if the directory exists) -4. `.ai-repo/config/artifact-layout.json` — Artifact layout overrides (if it exists) -5. `work/decisions.md` — Active decisions -6. `work/agent-history/` — Learnings from past sessions (read the file matching current role) - -The `.claude/` directory and `CLAUDE.md` are shared assistant-neutral surfaces. -Generated adapter files under `.github/` and `.claude/` are local build outputs. -Source of truth: `.ai/` and `.ai-repo/`. Regenerate with `bash .ai/sync.sh`. - -## Hard Rules (summary — full rules in `.ai/rules.md`) - -- **NEVER commit or push without explicit human approval** -- **TDD by default** for logic, API, and data code -- **Branch coverage** — every reachable conditional branch needs a test before declaring done; perform a line-by-line audit before the commit-approval prompt -- **Identify the agent first** — read the agent file before writing code -- **Branch discipline** — do NOT commit milestone work directly to `main` -- Follow Conventional Commits format - -## Agent Routing - -For specific personas, switch to a named agent: planner, builder, reviewer, deployer. - -| Intent | Agent | Read first | -|--------|-------|------------| -| build, implement, code, start, fix, patch | **builder** | `.claude/agents/builder.md` + relevant skill | -| plan, design, scope, epic, architecture | **planner** | `.claude/agents/planner.md` + relevant skill | -| review, check, validate, wrap, finish | **reviewer** | `.claude/agents/reviewer.md` + relevant skill | -| release, deploy, tag, publish | **deployer** | `.claude/agents/deployer.md` + relevant skill | - -Agents: `.claude/agents/`. Skills: `.claude/skills/`. Templates: `.ai/templates/`. -Project extensions: `.ai-repo/` (config, agents, skills, rules). - -## Workflow Modes - -| Mode | When | What happens | -|------|------|-------------| -| **Quick** | One-off fixes, typos, config changes | `patch` skill. No spec, no tracking doc. | -| **Standard** | Milestone-scoped work with acceptance criteria | spec → branch → TDD → tracking doc → review → merge | -| **Epic** | Multi-milestone features, new systems | Plan → milestones → Standard for each → release | - -## Context Refresh - -When the user says **"refresh context"** or **"refresh"**: -1. Re-read `.ai/rules.md`, `.ai/paths.md`, `.ai-repo/rules/`, and `.ai-repo/config/artifact-layout.json` -2. Re-read the active agent file if one is invoked -3. Read `CLAUDE.md` "Current Work" section -4. Read the roadmap at the path specified in the resolved artifact layout -5. Read `work/gaps.md` and `work/decisions.md` -6. Summarize: current branch, active phase, immediate tasks, known blockers - -## Resolved Artifact Layout - -These values are resolved from framework defaults in .ai/paths.md and repo overrides in .ai-repo/config/artifact-layout.json. - -| Field | Value | Purpose | -|-------|-------|---------| -| `roadmapPath` | `ROADMAP.md` | High-level roadmap path | -| `epicRootPath` | `work/epics/` | Root directory containing epic folders | -| `epicSpecFileName` | `spec.md` | Default epic spec filename inside each epic folder | -| `milestoneSpecPathTemplate` | `work/epics//.md` | Milestone spec location template | -| `trackingDocPathTemplate` | `work/epics//-tracking.md` | Milestone tracking doc location template | -| `completedEpicPathTemplate` | `work/epics/completed//` | Completed epic archive template | -| `epicIdPattern` | `E-{NN}` | Epic ID naming pattern | -| `milestoneIdPattern` | `m-E{NN}--` | Milestone ID naming pattern | -| `frameworkSkillPrefix` | `wf` | Prefix for framework skill slash-commands (e.g. `wf:patch`) | -| `repoSkillPrefix` | `` | Prefix for repo-specific skill slash-commands (e.g. `wf-li:app-legibility`) | - -## Project-Specific Rules - -# FlowTime Project Rules - -Project-specific conventions for the FlowTime mono-repo (Engine + Sim + UI). - ---- - -## Tooling - -- Prefer precise edits; stick to established patterns and avoid broad refactors without context. -- Use `rg`/`fd` for searches. - -## Project Layout - -- `src/FlowTime.Core`, `src/FlowTime.API`, `src/FlowTime.Cli`, `src/FlowTime.Contracts`, `src/FlowTime.Adapters.Synthetic` — Engine surface. -- `src/FlowTime.Sim.Core`, `src/FlowTime.Sim.Service`, `src/FlowTime.Sim.Cli` — Simulation surface. -- `src/FlowTime.UI`, `src/FlowTime.UI.Tests` — Blazor WebAssembly UI. -- `tests/` mirrors project names (e.g., `tests/FlowTime.Core.Tests`, `tests/FlowTime.Sim.Tests`, `tests/FlowTime.Api.Tests`). -- `docs/` — Engine/shared documentation. `docs-sim/` is archived — ignore unless explicitly requested. -- `work/` — AI framework housekeeping: epics, epic-local milestone specs/tracking docs, gaps, decisions. - -## Workflow Artifact Layout - -- The canonical artifact layout for this repo is defined in `.ai-repo/config/artifact-layout.json`. -- Older `*-log.md` files are historical and may remain until the related epic/docs are actively migrated. -- `work/milestones/` is a compatibility stub only. Do not create active specs or logs there. -- `ROADMAP.md` is the framework roadmap path. -- `work/epics/epic-roadmap.md` can remain as a supplemental epic index/sequencing document while it is still useful. - -## Milestone Status Sync - -- Milestone start and wrap must reconcile status across all repo-owned status surfaces in one pass: milestone spec, milestone tracking doc, epic milestone table (`work/epics//spec.md`), `ROADMAP.md`, `work/epics/epic-roadmap.md` when it mentions the epic, and `CLAUDE.md` current work. -- Do not leave an earlier milestone marked `in-progress` or `pending` once a later milestone in the same epic has started on a continuation branch. -- Treat status-surface drift as a workflow bug, not optional housekeeping. - -## Coding Conventions - -- .NET 9 / C# 13 with implicit usings and nullable enabled. -- Private fields **must use camelCase without a leading underscore** (`private readonly string dataDirectory;`). -- Follow existing patterns before introducing new abstractions; check for shared contracts in `FlowTime.Contracts`. -- Keep CLI ↔ API behaviour aligned; update relevant `.http` examples and docs when changing endpoints. -- Use invariant culture for parsing/formatting; keep tests deterministic. -- JSON payloads and schemas use camelCase — do not introduce snake_case fields. -- Never reintroduce deprecated schema fields (e.g., `binMinutes`); current schema uses `{ bins, binSize, binUnit }`. -- When inserting inline code containing `|` inside Markdown tables, escape the pipe as `\|`. - -## Branching & Versioning - -- Epic integration branches use `epic/E-{NN}-`. Every numbered epic gets an integration branch; milestone branches branch from it and merge back into it. -- Milestone branches use `milestone/`. -- Feature branches use `feature/-/` when a milestone needs parallel work. -- Single-surface quick changes can branch from `main` and PR directly back to `main` when no milestone integration branch is needed. -- Conventional commits: `feat(api):`, `fix(sim):`, `docs:`, etc. -- Commit messages: conventional prefix, no icons/emoji; subject + short bullet body capturing the milestone and key work/tests touched. -- Version format `..[-pre]`; milestone completions typically bump minor (e.g., `0.6.0 → 0.7.0`). -- Release notes in `docs/releases/` with milestone-based naming (e.g., `SIM-M2.7-v0.6.0.md`). - -## Build & Run - -- `dotnet build FlowTime.sln` / `dotnet test FlowTime.sln` -- VS Code tasks: `build`, `test`, `start-api`, `stop-api`, `start-sim-api`, `stop-sim-api`, `start-ui`, `stop-ui` -- Engine API: `dotnet run --project src/FlowTime.API` → port 8081 -- Sim API: `dotnet run --project src/FlowTime.Sim.Service` with `ASPNETCORE_URLS=http://0.0.0.0:8090` -- UI: `dotnet run --project src/FlowTime.UI` -- Default ports: 8081 (Engine API), 8090 (Sim API), 5219/7047 (UI), 8091 (Sim diagnostics), 5091 (Engine dev profile) -- Build and test before handing work back. - -## Devcontainer Port Safety - -- **Never blindly kill all processes on port 8081** — the devcontainer port-forwarder listens there; killing it destroys the session. -- To free port 8081, filter by process name: only kill `dotnet` processes. -- Use the `kill-port-8081` VS Code task — it filters safely. -- Verify processes before killing: `lsof -ti:PORT`, `ps aux | grep`. Use `pkill -f "ProcessName"` or `lsof -ti:PORT | xargs -r kill -TERM`. Never `kill `. -- Send SIGTERM first, wait, then SIGKILL only if still alive. Never start with `kill -9`. - -## Testing - -- Unit tests: fast and deterministic; no network or file-system side effects. -- API tests: use `WebApplicationFactory`; prefer real dependencies over mocks. -- Sim tests: `tests/FlowTime.Sim.Tests` — covers CLI, template parsing, provenance, service behaviours. -- Integration tests: `tests/FlowTime.Integration.Tests` for cross-surface scenarios. - -### UI testing (hard rule) - -- **UI work must be eval'd end-to-end in a real browser.** Every milestone that ships new or changed UI (Blazor or Svelte) must include Playwright tests that drive the feature in a real browser and verify the rendered outcome. Type checks and unit tests on pure helpers are necessary but not sufficient — they do not catch broken event handlers, state leaks, reactive glitches, or CSS-driven breakage. The user experience is the contract; a passing test must prove the user experience works. -- **Playwright infrastructure lives at `tests/ui/`** with config at `tests/ui/playwright.config.ts`, specs under `tests/ui/specs/`, and helpers under `tests/ui/helpers/`. Add new specs alongside existing ones. -- **Graceful skip when infrastructure is down.** If the API or dev server isn't running, the spec should skip with a clear message rather than fail. Follow the existing pattern used by the Rust engine integration tests (health probe → skip on unavailable). -- **Svelte UI runs on port 5173** (vite dev). **Blazor UI runs on port 5219**. Override `baseURL` per-spec if needed. -- **Vitest covers pure logic.** Svelte/TS pure functions (helpers, store derivations, protocol encoding) should have vitest unit tests in `ui/src/**/*.test.ts`. These run fast and guard the foundation; Playwright guards the integration. -- **Cover the critical paths.** For each user-facing surface: (1) page loads and renders expected initial state, (2) at least one user interaction drives a visible change, (3) reset/undo/error-recovery paths behave correctly, (4) key latency or correctness metrics that the UI exposes actually display correct values. - -## Truth Discipline - -### Precedence (highest to lowest) -1. **Code + passing tests** define live truth. -2. **`work/decisions.md`** defines approved direction. -3. **Epic specs and epic-local milestone specs** under `work/epics/` define implementation target, within their scope. -4. **Architecture docs** (`docs/`) summarize and connect the above — they never outrank code or decisions. -5. **Historical and exploration docs** are context only — never implementation authority. - -If code, decisions.md, and an architecture doc disagree, do not choose arbitrarily. Report the mismatch and ask. - -### Truth classes -- **`docs/`** — current ground truth. If it's in `docs/`, it describes what IS (shipped, provable by code/tests). -- **`work/epics/`** — decided-next and exploration. Proposals, specs, architectural direction for future work. -- **`docs/archive/`**, **`docs/releases/`** — historical. What WAS. Do not use for current state. -- **`docs/notes/`** — exploration only. Brainstorming, research, ideas. Never treat as implementation authority. - -### Guards -- Do not describe a target contract in present tense unless it is live. -- Do not let one file simultaneously act as current reference and historical archive. -- Do not restate a canonical contract in many places from memory — point to the owning doc. -- Do not let adapter/UI projection become the only place where semantics exist. -- Do not keep "temporary" compatibility shims without explicit deletion criteria. -- When a milestone explicitly owns a bridge or cleanup seam, do not preserve the bridge helper past that milestone as a tolerated coexistence state. Treat the surviving helper as incomplete work. -- Do not reconstruct semantic or analytical identity in adapters or clients from `kind`, `logicalType`, file stems, or similar heuristics when compiled/runtime facts can own that truth. -- When a runtime boundary changes, prefer forward-only regeneration of runs, fixtures, and approved outputs over compatibility readers that recover missing facts. -- Do not keep both a bridge abstraction and its compiled replacement once the replacement milestone is active unless the spec explicitly allows a coexistence window. -- Do not treat aspirational docs as implementation authority. - -## Documentation - -- Engine + shared docs in `docs/`; use Mermaid for diagrams (not ASCII art). -- Keep docs/schemas/templates aligned when touching contracts or schemas. -- Repository language: English. No time or effort estimates in docs or plans. -- Treat sibling checkouts as read-only references unless the user instructs otherwise. diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..0941ac21 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,6 @@ +{ + "statusLine": { + "type": "command", + "command": "bash .claude/statusline.sh" + } +} diff --git a/.claude/statusline.sh b/.claude/statusline.sh new file mode 100755 index 00000000..38a0d45f --- /dev/null +++ b/.claude/statusline.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash +# statusline.sh — Claude Code status line for AI Framework v2 projects. +# +# Reads a JSON payload on stdin (provided by Claude Code per invocation) +# and prints a single line to stdout. Shows: +# [ ] +# +# Thresholds: +# 🟢 green tokens < 250k +# 🟡 yellow 250k ≤ tokens < 500k ("consider new session") +# 🔴 red tokens ≥ 500k ("START NEW SESSION") +# +# Epic/milestone detection: +# - Epic ID: first `E-` match in `work/roadmap.md` +# - Milestone ID: first `M--` match in `CLAUDE.md` "Current Work" +# Falls back silently when the repo doesn't match the framework's layout. +# +# Token counting: parses the last `"usage"` record in the transcript JSONL +# and sums input_tokens + cache_read + cache_creation. Zero if unavailable. +# +# Requires: jq, bash, coreutils (tac, basename, grep, cat). + +set -u + +input=$(cat) + +# ── Parse Claude Code stdin payload ───────────── +cwd=$(jq -r '.cwd // .workspace.current_dir // empty' <<<"$input" 2>/dev/null) +model_name=$(jq -r '.model.display_name // .model.id // "Claude"' <<<"$input" 2>/dev/null) +transcript_path=$(jq -r '.transcript_path // empty' <<<"$input" 2>/dev/null) +cwd=${cwd:-$PWD} + +# ── Working directory (basename shows worktree names as-is) ── +dir=$(basename "$cwd") + +# ── Active epic / milestone from the framework's artefact layout ── +epic="" +milestone="" +if [ -f "$cwd/work/roadmap.md" ]; then + epic=$(grep -m1 -oE 'E-[A-Z][A-Za-z0-9-]+' "$cwd/work/roadmap.md" 2>/dev/null | head -1) +fi +if [ -f "$cwd/CLAUDE.md" ]; then + # Scope to the Current Work section so we don't match M-IDs in routing tables. + milestone=$(awk '/^## Current Work/{found=1} found' "$cwd/CLAUDE.md" 2>/dev/null \ + | grep -m1 -oE 'M-[A-Z0-9]+-[0-9]+[A-Za-z0-9-]*' | head -1) +fi +tag="" +if [ -n "$epic" ] && [ -n "$milestone" ]; then + tag="$epic $milestone" +elif [ -n "$epic" ]; then + tag="$epic" +elif [ -n "$milestone" ]; then + tag="$milestone" +fi + +# ── Context tokens (last usage record in the transcript) ── +tokens=0 +if [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then + usage_line=$(tac "$transcript_path" 2>/dev/null | grep -m1 '"usage"' || true) + if [ -n "$usage_line" ]; then + tokens=$(jq -r ' + (.message.usage // .usage // {}) | + ((.input_tokens // 0) + + (.cache_read_input_tokens // 0) + + (.cache_creation_input_tokens // 0)) + ' <<<"$usage_line" 2>/dev/null || echo 0) + fi +fi +tokens=${tokens:-0} + +# ── Threshold icon / colour / warning ── +if [ "$tokens" -ge 500000 ]; then icon="🔴"; color=31; warn=" · START NEW SESSION" +elif [ "$tokens" -ge 250000 ]; then icon="🟡"; color=33; warn=" · consider new session" +else icon="🟢"; color=32; warn="" +fi +tokens_k=$((tokens / 1000)) + +# ── Render: icon hugs the first text part; the rest join with " · " ── +parts=("$model_name" "$dir") +[ -n "$tag" ] && parts+=("$tag") +parts+=("$(printf '\033[%sm%dk tokens\033[0m%s' "$color" "$tokens_k" "$warn")") + +body="" +for p in "${parts[@]}"; do + if [ -z "$body" ]; then body="$p"; else body="$body · $p"; fi +done +printf '%s %s' "$icon" "$body" diff --git a/.codex/instructions.md b/.codex/instructions.md index bbfdc897..e4edd55c 100644 --- a/.codex/instructions.md +++ b/.codex/instructions.md @@ -1,13 +1,13 @@ # AI Framework v2 - + Read and follow: 1. `.ai/rules.md` — Non-negotiable guardrails 2. `.ai/paths.md` — Where artifacts live -Agents: `.ai/agents/` (planner, builder, reviewer, deployer) -Skills: `.ai/skills/` (plan-epic, plan-milestones, draft-spec, start-milestone, tdd-cycle, review-code, wrap-milestone, release) -Templates: `.ai/templates/` (epic-spec, milestone-spec, tracking-doc) +Agents: `.ai/agents/` (builder, deployer, planner, reviewer) +Skills: `.ai/skills/` (architect, devcontainer, doc-gardening, draft-spec, patch, plan-epic, plan-milestones, quality-score, release, review-code, start-milestone, tdd-cycle, workflow-audit, wrap-milestone) +Templates: `.ai/templates/` (app-legibility, epic-spec, milestone-spec, quality-scorecard, session-log, tracking-doc) Key rules: - Never commit without explicit human approval diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index fdb18ca1..00000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,206 +0,0 @@ -# Copilot Instructions - - -## AI Framework - -This project uses the AI-Assisted Development Framework v2. - -Recent GitHub Copilot versions may also read `CLAUDE.md` and `.claude/` automatically. -In this repo, those are intentionally assistant-neutral shared surfaces, not Claude-only overrides. -Generated adapter files under `.github/` and `.claude/` are local build outputs. -Keep their source of truth in `.ai/` and `.ai-repo/`, and regenerate with `bash .ai/sync.sh`. - -**Before starting any task**, read these files: -- `.ai/rules.md` — Non-negotiable guardrails (full rules and enforcement levels live here) -- `.ai/paths.md` — Artifact layout defaults -- `.ai-repo/rules/` — Project-specific rules and conventions (if the directory exists) -- `.ai-repo/config/artifact-layout.json` — Artifact layout overrides (if it exists) -- `work/decisions.md` — Active decisions the team has made -- `work/agent-history/` — Learnings from past sessions (read the file matching current role) - -## Hard Rules (summary — full rules in `.ai/rules.md`) - -- **NEVER commit or push without explicit human approval** -- **TDD by default** for logic, API, and data code -- **Branch coverage** — every reachable conditional branch needs a test before declaring done; perform a line-by-line audit before the commit-approval prompt -- **Identify the agent first** — read the agent file before writing code -- **Branch discipline** — do NOT commit milestone work directly to `main` -- Follow Conventional Commits format - -## Agent Routing - -Switch to a named agent for specific workflows: @planner, @builder, @reviewer, @deployer. - -| Intent | Agent | Read first | -|--------|-------|------------| -| build, implement, code, start, fix, patch | **@builder** | `.claude/agents/builder.md` + relevant skill | -| plan, design, scope, epic, architecture | **@planner** | `.claude/agents/planner.md` + relevant skill | -| review, check, validate, wrap, finish | **@reviewer** | `.claude/agents/reviewer.md` + relevant skill | -| release, deploy, tag, publish | **@deployer** | `.claude/agents/deployer.md` + relevant skill | - -**Available skills:** architect, devcontainer, doc-gardening, draft-spec, patch, plan-epic, plan-milestones, quality-score, release, review-code, start-milestone, tdd-cycle, wrap-milestone -**Project-specific skills:** ui-debug (see `.ai-repo/skills/`) -**Templates:** epic-spec, milestone-spec, tracking-doc (see `.ai/templates/`) - -## Workflow Modes - -| Mode | When | What happens | -|------|------|-------------| -| **Quick** | One-off fixes, typos, config changes | `patch` skill. No spec, no tracking doc. | -| **Standard** | Milestone-scoped work with acceptance criteria | spec → branch → TDD → tracking doc → review → merge | -| **Epic** | Multi-milestone features, new systems | Plan epic → milestones → Standard for each → release | - -## Context Refresh - -When the user says **"refresh context"** or **"refresh"**: -1. Re-read `.ai/rules.md`, `.ai/paths.md`, `.ai-repo/rules/`, and `.ai-repo/config/artifact-layout.json` -2. Re-read the active agent file if one is invoked -3. Read `CLAUDE.md` "Current Work" section -4. Read the roadmap at the path specified in the resolved artifact layout -5. Read `work/gaps.md` and `work/decisions.md` -6. Summarize: current branch, active phase, immediate tasks, known blockers - -## Resolved Artifact Layout - -These values are resolved from framework defaults in .ai/paths.md and repo overrides in .ai-repo/config/artifact-layout.json. - -| Field | Value | Purpose | -|-------|-------|---------| -| `roadmapPath` | `ROADMAP.md` | High-level roadmap path | -| `epicRootPath` | `work/epics/` | Root directory containing epic folders | -| `epicSpecFileName` | `spec.md` | Default epic spec filename inside each epic folder | -| `milestoneSpecPathTemplate` | `work/epics//.md` | Milestone spec location template | -| `trackingDocPathTemplate` | `work/epics//-tracking.md` | Milestone tracking doc location template | -| `completedEpicPathTemplate` | `work/epics/completed//` | Completed epic archive template | -| `epicIdPattern` | `E-{NN}` | Epic ID naming pattern | -| `milestoneIdPattern` | `m-E{NN}--` | Milestone ID naming pattern | -| `frameworkSkillPrefix` | `wf` | Prefix for framework skill slash-commands (e.g. `wf:patch`) | -| `repoSkillPrefix` | `` | Prefix for repo-specific skill slash-commands (e.g. `wf-li:app-legibility`) | - -## Project-Specific Rules - -# FlowTime Project Rules - -Project-specific conventions for the FlowTime mono-repo (Engine + Sim + UI). - ---- - -## Tooling - -- Prefer precise edits; stick to established patterns and avoid broad refactors without context. -- Use `rg`/`fd` for searches. - -## Project Layout - -- `src/FlowTime.Core`, `src/FlowTime.API`, `src/FlowTime.Cli`, `src/FlowTime.Contracts`, `src/FlowTime.Adapters.Synthetic` — Engine surface. -- `src/FlowTime.Sim.Core`, `src/FlowTime.Sim.Service`, `src/FlowTime.Sim.Cli` — Simulation surface. -- `src/FlowTime.UI`, `src/FlowTime.UI.Tests` — Blazor WebAssembly UI. -- `tests/` mirrors project names (e.g., `tests/FlowTime.Core.Tests`, `tests/FlowTime.Sim.Tests`, `tests/FlowTime.Api.Tests`). -- `docs/` — Engine/shared documentation. `docs-sim/` is archived — ignore unless explicitly requested. -- `work/` — AI framework housekeeping: epics, epic-local milestone specs/tracking docs, gaps, decisions. - -## Workflow Artifact Layout - -- The canonical artifact layout for this repo is defined in `.ai-repo/config/artifact-layout.json`. -- Older `*-log.md` files are historical and may remain until the related epic/docs are actively migrated. -- `work/milestones/` is a compatibility stub only. Do not create active specs or logs there. -- `ROADMAP.md` is the framework roadmap path. -- `work/epics/epic-roadmap.md` can remain as a supplemental epic index/sequencing document while it is still useful. - -## Milestone Status Sync - -- Milestone start and wrap must reconcile status across all repo-owned status surfaces in one pass: milestone spec, milestone tracking doc, epic milestone table (`work/epics//spec.md`), `ROADMAP.md`, `work/epics/epic-roadmap.md` when it mentions the epic, and `CLAUDE.md` current work. -- Do not leave an earlier milestone marked `in-progress` or `pending` once a later milestone in the same epic has started on a continuation branch. -- Treat status-surface drift as a workflow bug, not optional housekeeping. - -## Coding Conventions - -- .NET 9 / C# 13 with implicit usings and nullable enabled. -- Private fields **must use camelCase without a leading underscore** (`private readonly string dataDirectory;`). -- Follow existing patterns before introducing new abstractions; check for shared contracts in `FlowTime.Contracts`. -- Keep CLI ↔ API behaviour aligned; update relevant `.http` examples and docs when changing endpoints. -- Use invariant culture for parsing/formatting; keep tests deterministic. -- JSON payloads and schemas use camelCase — do not introduce snake_case fields. -- Never reintroduce deprecated schema fields (e.g., `binMinutes`); current schema uses `{ bins, binSize, binUnit }`. -- When inserting inline code containing `|` inside Markdown tables, escape the pipe as `\|`. - -## Branching & Versioning - -- Epic integration branches use `epic/E-{NN}-`. Every numbered epic gets an integration branch; milestone branches branch from it and merge back into it. -- Milestone branches use `milestone/`. -- Feature branches use `feature/-/` when a milestone needs parallel work. -- Single-surface quick changes can branch from `main` and PR directly back to `main` when no milestone integration branch is needed. -- Conventional commits: `feat(api):`, `fix(sim):`, `docs:`, etc. -- Commit messages: conventional prefix, no icons/emoji; subject + short bullet body capturing the milestone and key work/tests touched. -- Version format `..[-pre]`; milestone completions typically bump minor (e.g., `0.6.0 → 0.7.0`). -- Release notes in `docs/releases/` with milestone-based naming (e.g., `SIM-M2.7-v0.6.0.md`). - -## Build & Run - -- `dotnet build FlowTime.sln` / `dotnet test FlowTime.sln` -- VS Code tasks: `build`, `test`, `start-api`, `stop-api`, `start-sim-api`, `stop-sim-api`, `start-ui`, `stop-ui` -- Engine API: `dotnet run --project src/FlowTime.API` → port 8081 -- Sim API: `dotnet run --project src/FlowTime.Sim.Service` with `ASPNETCORE_URLS=http://0.0.0.0:8090` -- UI: `dotnet run --project src/FlowTime.UI` -- Default ports: 8081 (Engine API), 8090 (Sim API), 5219/7047 (UI), 8091 (Sim diagnostics), 5091 (Engine dev profile) -- Build and test before handing work back. - -## Devcontainer Port Safety - -- **Never blindly kill all processes on port 8081** — the devcontainer port-forwarder listens there; killing it destroys the session. -- To free port 8081, filter by process name: only kill `dotnet` processes. -- Use the `kill-port-8081` VS Code task — it filters safely. -- Verify processes before killing: `lsof -ti:PORT`, `ps aux | grep`. Use `pkill -f "ProcessName"` or `lsof -ti:PORT | xargs -r kill -TERM`. Never `kill `. -- Send SIGTERM first, wait, then SIGKILL only if still alive. Never start with `kill -9`. - -## Testing - -- Unit tests: fast and deterministic; no network or file-system side effects. -- API tests: use `WebApplicationFactory`; prefer real dependencies over mocks. -- Sim tests: `tests/FlowTime.Sim.Tests` — covers CLI, template parsing, provenance, service behaviours. -- Integration tests: `tests/FlowTime.Integration.Tests` for cross-surface scenarios. - -### UI testing (hard rule) - -- **UI work must be eval'd end-to-end in a real browser.** Every milestone that ships new or changed UI (Blazor or Svelte) must include Playwright tests that drive the feature in a real browser and verify the rendered outcome. Type checks and unit tests on pure helpers are necessary but not sufficient — they do not catch broken event handlers, state leaks, reactive glitches, or CSS-driven breakage. The user experience is the contract; a passing test must prove the user experience works. -- **Playwright infrastructure lives at `tests/ui/`** with config at `tests/ui/playwright.config.ts`, specs under `tests/ui/specs/`, and helpers under `tests/ui/helpers/`. Add new specs alongside existing ones. -- **Graceful skip when infrastructure is down.** If the API or dev server isn't running, the spec should skip with a clear message rather than fail. Follow the existing pattern used by the Rust engine integration tests (health probe → skip on unavailable). -- **Svelte UI runs on port 5173** (vite dev). **Blazor UI runs on port 5219**. Override `baseURL` per-spec if needed. -- **Vitest covers pure logic.** Svelte/TS pure functions (helpers, store derivations, protocol encoding) should have vitest unit tests in `ui/src/**/*.test.ts`. These run fast and guard the foundation; Playwright guards the integration. -- **Cover the critical paths.** For each user-facing surface: (1) page loads and renders expected initial state, (2) at least one user interaction drives a visible change, (3) reset/undo/error-recovery paths behave correctly, (4) key latency or correctness metrics that the UI exposes actually display correct values. - -## Truth Discipline - -### Precedence (highest to lowest) -1. **Code + passing tests** define live truth. -2. **`work/decisions.md`** defines approved direction. -3. **Epic specs and epic-local milestone specs** under `work/epics/` define implementation target, within their scope. -4. **Architecture docs** (`docs/`) summarize and connect the above — they never outrank code or decisions. -5. **Historical and exploration docs** are context only — never implementation authority. - -If code, decisions.md, and an architecture doc disagree, do not choose arbitrarily. Report the mismatch and ask. - -### Truth classes -- **`docs/`** — current ground truth. If it's in `docs/`, it describes what IS (shipped, provable by code/tests). -- **`work/epics/`** — decided-next and exploration. Proposals, specs, architectural direction for future work. -- **`docs/archive/`**, **`docs/releases/`** — historical. What WAS. Do not use for current state. -- **`docs/notes/`** — exploration only. Brainstorming, research, ideas. Never treat as implementation authority. - -### Guards -- Do not describe a target contract in present tense unless it is live. -- Do not let one file simultaneously act as current reference and historical archive. -- Do not restate a canonical contract in many places from memory — point to the owning doc. -- Do not let adapter/UI projection become the only place where semantics exist. -- Do not keep "temporary" compatibility shims without explicit deletion criteria. -- When a milestone explicitly owns a bridge or cleanup seam, do not preserve the bridge helper past that milestone as a tolerated coexistence state. Treat the surviving helper as incomplete work. -- Do not reconstruct semantic or analytical identity in adapters or clients from `kind`, `logicalType`, file stems, or similar heuristics when compiled/runtime facts can own that truth. -- When a runtime boundary changes, prefer forward-only regeneration of runs, fixtures, and approved outputs over compatibility readers that recover missing facts. -- Do not keep both a bridge abstraction and its compiled replacement once the replacement milestone is active unless the spec explicitly allows a coexistence window. -- Do not treat aspirational docs as implementation authority. - -## Documentation - -- Engine + shared docs in `docs/`; use Mermaid for diagrams (not ASCII art). -- Keep docs/schemas/templates aligned when touching contracts or schemas. -- Repository language: English. No time or effort estimates in docs or plans. -- Treat sibling checkouts as read-only references unless the user instructs otherwise. diff --git a/.github/skills/architect/SKILL.md b/.github/skills/architect/SKILL.md deleted file mode 100644 index 9300baec..00000000 --- a/.github/skills/architect/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -description: Brainstorming, architecture, and research skill. Used by the planner agent for ideation, technical design, and research documentation. -name: architect -when_to_use: | - - When the user requests brainstorming, architecture, design, or research work - - When planning new features or evaluating technical approaches - - When documenting research findings or architectural decisions -responsibilities: - - Facilitate brainstorming and ideation sessions - - Propose and evaluate architectural patterns and trade-offs - - Document research findings in docs/research - - Write or update architecture docs in docs/architecture - - Draft technical specs in docs/specs (if needed) - - Summarize alternatives, risks, and recommendations -output: - - Markdown documentation (architecture, research, or specs) - - Decision records or trade-off analyses - - Clear, actionable recommendations for next steps -invoked_by: - - planner agent (automatically when brainstorming, architecture, or research is requested) ---- - -# Skill: Architect - -This skill enables the planner agent to: -- Lead brainstorming and ideation sessions -- Propose and evaluate technical architectures -- Document research and design work -- Produce actionable, well-structured outputs for the team - -## File Placement -- Research: docs/research/ -- Architecture: docs/architecture/ -- Specs: docs/specs/ - -## Example Triggers -- "Let's brainstorm approaches for X" -- "Can you design an architecture for Y?" -- "Research the best way to do Z" -- "Write an ADR for this decision" -- "Document the trade-offs between A and B" - -## Best Practices -- Always cite sources or rationale for recommendations -- Use diagrams or tables where helpful -- Keep outputs concise, actionable, and easy to find - -## Record Learnings - -After completing research or architecture work: -- Append key decisions to `work/decisions.md` (use the standard decision format) -- Append research insights or architectural patterns to `work/agent-history/planner.md` -- Note: only record things worth remembering across sessions — not every detail diff --git a/.github/skills/devcontainer/SKILL.md b/.github/skills/devcontainer/SKILL.md deleted file mode 100644 index d25322d2..00000000 --- a/.github/skills/devcontainer/SKILL.md +++ /dev/null @@ -1,290 +0,0 @@ ---- -description: Create, maintain, and operate VS Code devcontainers with correct mount topology, worktree support, and persistence guarantees. -name: devcontainer -when_to_use: | - - When creating a new devcontainer for a project - - When modifying devcontainer configuration (Dockerfile, mounts, post-create) - - When setting up or recovering git worktrees inside a devcontainer - - When diagnosing lost data or mount issues after a container rebuild - - When a user asks "set up a devcontainer" or "fix the container" -responsibilities: - - Configure devcontainer.json with correct mount topology - - Write Dockerfiles with the project's required toolchain - - Write post-create scripts for dependency setup - - Set up git worktrees at mount-safe locations - - Maintain .dockerignore for build context hygiene - - Diagnose and fix persistence issues across container rebuilds -output: - - .devcontainer/devcontainer.json - - .devcontainer/Dockerfile - - .devcontainer/post-create.sh - - .dockerignore - - Working worktree at a rebuild-safe location -invoked_by: - - builder agent (when devcontainer setup or modification is needed) - - planner agent (when scoping a new project's infrastructure) ---- - -# Skill: Devcontainer - -Create and maintain VS Code devcontainers that are safe across rebuilds, support git worktrees, and work identically whether accessed locally or via SSH. - -## Core Concepts - -### Host vs Container - -``` -Host machine (macOS / Linux) -├── ~/Projects// ← git repo on host disk -├── ~/Projects/worktrees/ ← sibling dir for worktrees (host disk) -├── ~/.claude/ ← Claude Code config (host disk) -│ -└── Docker container - ├── /workspaces// ← bind-mount of repo - ├── /workspaces/worktrees/ ← bind-mount of sibling worktrees dir - ├── /home/vscode/.claude/ ← bind-mount of ~/.claude - └── everything else ← EPHEMERAL, lost on rebuild -``` - -**Rule: anything that must survive a container rebuild must be on a bind mount — either the workspace mount or an explicit additional mount.** - -### Persistence classification - -| Location | Survives rebuild | Why | -|---|---|---| -| `/workspaces//` | yes | workspace bind mount | -| `/workspaces/worktrees/` | yes | explicit bind mount (sibling of repo on host) | -| `/home/vscode/.claude/` | yes | explicit bind mount | -| gitignored files under the workspace | yes | they're on the workspace mount | -| `/home/vscode/.cache/`, `/tmp/`, `_build/` | **no** | container-local filesystem | - -## devcontainer.json Template - -```jsonc -{ - "name": "", - "build": { - "dockerfile": "Dockerfile" - }, - // Mount the PARENT directory so sibling dirs (worktrees, other repos) - // are automatically visible inside the container. - "workspaceFolder": "/workspaces/", - "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind,consistency=cached", - // Symlink trick: initializeCommand runs on the HOST where $HOME is - // always correct. Avoids ${localEnv:HOME} which is unreliable across - // local vs SSH vs reopened sessions. - "initializeCommand": "ln -sfn \"$HOME/.claude\" /tmp/.claude-mount", - "postCreateCommand": "bash .devcontainer/post-create.sh", - "remoteUser": "vscode", - "mounts": [ - "source=/tmp/.claude-mount,target=/home/vscode/.claude,type=bind,consistency=cached" - ], - "customizations": { - "vscode": { - "extensions": [ - // Add project-relevant extensions here - "anthropics.claude-code" - ] - } - } -} -``` - -### Why this topology - -- **`workspaceMount` mounts the parent**: one mount gives access to the repo, worktrees, and any sibling dirs. No need to add explicit mounts for each new worktree or sibling repo. -- **`initializeCommand` symlink for `.claude`**: runs on the host before container creation; `$HOME` is always the host user's home regardless of how VS Code was launched (local, Remote SSH, reopen after restart). -- **No `${localEnv:HOME}`**: this variable is set from VS Code's process environment, which can differ between local, SSH, and background sessions. - -## Dockerfile Strategy - -### Choosing a base image - -Pick the base image based on the project's primary runtime: - -| Primary runtime | Base image | Notes | -|---|---|---| -| Python + Node (most projects) | `debian:bookworm-slim` | Install Python, uv, Node yourself — full control | -| Elixir/OTP | `hexpm/elixir:-erlang--debian-bookworm-slim` | Add Python/Node on top | -| .NET | `mcr.microsoft.com/devcontainers/dotnet:` | Microsoft prebuilt; includes git, sudo, non-root user. Add Python/Node on top | -| Rust | `rust:-slim-bookworm` | Add Python/Node on top | -| Go | `golang:-bookworm` | Add Python/Node on top | - -When using Microsoft prebuilt images (`mcr.microsoft.com/devcontainers/*`), skip the non-root user setup and Claude Code CLI sections below — those images already provide a `vscode` user and can install tools via features. The common system packages, Python/uv, and Node sections still apply if not already included. - -### Dockerfile template (Debian-based) - -For non-prebuilt base images, always include: - -```dockerfile -# Common system packages -RUN apt-get update && apt-get install -y --no-install-recommends \ - build-essential \ - curl \ - git \ - sudo \ - zsh \ - && rm -rf /var/lib/apt/lists/* - -# Node.js LTS (required by most projects for tooling) -ARG NODE_MAJOR=22 -RUN curl -fsSL https://deb.nodesource.com/setup_${NODE_MAJOR}.x | bash - \ - && apt-get install -y --no-install-recommends nodejs \ - && rm -rf /var/lib/apt/lists/* - -# Python via Astral uv (preferred over pip/venv for reproducibility) -RUN apt-get update && apt-get install -y --no-install-recommends \ - python3 python3-venv \ - && rm -rf /var/lib/apt/lists/* -COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ - -# GitHub CLI (for PR workflows) -RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \ - | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \ - && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \ - | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \ - && apt-get update && apt-get install -y --no-install-recommends gh \ - && rm -rf /var/lib/apt/lists/* - -# Non-root user for VS Code -ARG USERNAME=vscode -ARG USER_UID=1000 -ARG USER_GID=${USER_UID} -RUN groupadd --gid ${USER_GID} ${USERNAME} \ - && useradd --uid ${USER_UID} --gid ${USER_GID} -m ${USERNAME} \ - && echo "${USERNAME} ALL=(root) NOPASSWD:ALL" > /etc/sudoers.d/${USERNAME} \ - && chmod 0440 /etc/sudoers.d/${USERNAME} \ - && chsh -s /bin/zsh ${USERNAME} - -USER ${USERNAME} - -# Claude Code CLI -ENV PATH="/home/${USERNAME}/.local/bin:${PATH}" -RUN curl -fsSL https://claude.ai/install.sh | bash -``` - -### Language-specific additions - -Add before the non-root user block as needed: - -- **Elixir/OTP**: use `hexpm/elixir` as base image, add `mix local.hex --force && mix local.rebar --force` for both root and vscode users -- **.NET**: prefer `mcr.microsoft.com/devcontainers/dotnet` as base image — it includes the SDK, non-root user, and common devcontainer features out of the box. Only add the Python/uv and Node blocks if not already present. -- **Rust**: add `rustup` installation -- **Go**: install from official tarball - -## post-create.sh Template - -```bash -#!/usr/bin/env bash -set -e -echo "==> Setting up development environment" - -# Install language-specific dependencies. -# Use conditional blocks so the script works even if a language dir -# is absent (e.g., in a fresh repo or a trimmed clone). - -# Python environments (uv-managed) -for dir in runtime/python integrations/python; do - if [ -f "$dir/pyproject.toml" ]; then - echo "==> Installing Python deps in $dir..." - (cd "$dir" && uv sync) - fi -done - -# Node.js -if [ -f "package.json" ]; then - echo "==> Installing Node deps..." - npm install -fi - -# Elixir (if present) -if [ -f "mix.exs" ] || [ -d "runtime" ] && [ -f "runtime/mix.exs" ]; then - echo "==> Installing Elixir deps..." - (cd runtime 2>/dev/null || true; mix deps.get 2>/dev/null || true) -fi - -echo "==> Done." -``` - -## .dockerignore Template - -``` -.git -_build/ -deps/ -node_modules/ -__pycache__/ -*.pyc -.venv/ -.env -.env.* -*.secret -runtime/data/ -.claude/worktrees/ -``` - -## Git Worktree Operations - -### Creating a worktree - -Always create worktrees under the mounted sibling path, never in container-local storage: - -```bash -# Good — survives container rebuild -git worktree add /workspaces/worktrees/ - -# Bad — lost on rebuild -git worktree add /home/vscode/worktrees/ -git worktree add /tmp/worktrees/ -``` - -After creating, always init submodules: - -```bash -cd /workspaces/worktrees/ -git submodule update --init --recursive -``` - -### Recovering after container rebuild - -If the container was rebuilt but the worktree mount survived, git may not know about the worktree (its registration was in `.git/worktrees/` which was re-cloned): - -```bash -# Check: does git know about the worktree? -git worktree list - -# If the worktree dir exists on disk but git doesn't list it, -# re-add it (git detects existing checkout): -git worktree add /workspaces/worktrees/ -# Then re-init submodules -cd /workspaces/worktrees/ -git submodule update --init --recursive -``` - -### Reviewing worktree code in VS Code - -The worktree is at `/workspaces/worktrees/` — outside the VS Code workspace root. Options for reviewing: - -1. **Second VS Code window** (recommended): Attach to the running container, open `/workspaces/worktrees/` as workspace. Full explorer, search, git — no search pollution in the main workspace. -2. **Open individual files**: from the integrated terminal, `code /workspaces/worktrees//path/to/file` opens it in the current editor. -3. **Terminal review**: use `git diff`, `less`, `bat` in the integrated terminal. - -Do NOT put the worktree inside the main workspace — it duplicates the entire repo tree and pollutes search. - -## Operational Rules - -1. **Durable data must be on a bind mount.** If losing a directory on rebuild is a problem, it must live under the workspace mount or an explicit additional mount. -2. **`_build`, `/tmp`, caches are always disposable.** They may survive some rebuilds by accident (they're under the workspace mount if inside the repo tree), but they are not canonical data homes. -3. **Caches are performance aids, not truth.** `/home/vscode/.cache/` (uv, pip, huggingface, mix) is rebuildable. Expensive to re-download, but not project state. -4. **One container per project.** If you see multiple containers for the same project, the older one is stale. Stop and remove it. -5. **Worktrees go in `/workspaces/worktrees/`.** The parent-dir mount makes this path automatically available. Submodules must be re-initialized after worktree creation. - -## Safe To Clean - -| What | Where | Safe? | -|---|---|---| -| Container-local temp files | `/tmp/*` | always safe | -| Tool caches | `/home/vscode/.cache/` | safe (costs re-download time) | -| Build artifacts | `_build/`, `node_modules/`, `.venv/` | safe (costs rebuild time) | -| Runtime data | `runtime/data/` (or project equivalent) | **not safe** — this is durable local state | -| Git worktrees | `/workspaces/worktrees/` | **not safe** — contains work in progress | diff --git a/.github/skills/doc-gardening/SKILL.md b/.github/skills/doc-gardening/SKILL.md deleted file mode 100644 index a5aa71e7..00000000 --- a/.github/skills/doc-gardening/SKILL.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: Scan for stale, orphaned, or drifted documentation and workspace artifacts. Produces a health report and optionally fixes issues. -name: doc-gardening -when_to_use: | - - Periodic housekeeping between milestones - - When you suspect docs have drifted from code - - When work/gaps.md or work/decisions.md may be stale - - When the user asks to clean up, audit, or tidy docs -responsibilities: - - Detect status-surface drift (milestone spec vs tracking doc vs roadmap vs CLAUDE.md) - - Find stale decisions (active decisions whose code has moved on) - - Identify orphaned docs (files not referenced from any index or spec) - - Check for TODO/FIXME comments without linked tracking - - Flag gaps.md items that may already be resolved -output: - - Health report (Markdown) listing findings by category - - Optionally: direct fixes for simple drift (status updates, dead-link removal) -invoked_by: - - reviewer agent (between milestones or during wrap) - - any agent when the user requests a cleanup audit ---- - -# Skill: Doc Gardening - -Scan the workspace for documentation health issues and produce an actionable report. - -## Checklist - -### 1. Status-Surface Drift - -Check that milestone/epic status is consistent across all surfaces: -- [ ] Milestone spec status matches tracking doc status -- [ ] Epic milestone table matches individual milestone specs -- [ ] `ROADMAP.md` matches epic specs -- [ ] `CLAUDE.md` current work section is accurate -- [ ] `work/epics/epic-roadmap.md` (if present) is consistent - -Report any mismatches with file:line references. - -### 2. Stale Decisions - -- [ ] Read `work/decisions.md` -- [ ] For each `active` decision, check whether the code has moved past it (decision is now just "how things are" and can be marked `implemented`) -- [ ] For each `active` decision, check whether a later decision supersedes it -- [ ] Flag decisions older than 60 days that are still `active` - -### 3. Orphaned Files - -- [ ] Scan `docs/` for files not referenced from any index, spec, or README -- [ ] Scan `work/epics/` for folders not listed in any epic spec or roadmap -- [ ] Scan `work/epics/unplanned/` for folders that have been promoted to a numbered epic (now duplicated) - -### 4. Gaps Audit - -- [ ] Read `work/gaps.md` -- [ ] For each gap, check whether it has been addressed by a completed milestone -- [ ] Flag resolved gaps for removal - -### 5. Stale TODOs - -- [ ] Search for `TODO`, `FIXME`, `HACK`, `XXX` in source code -- [ ] Check whether each has a linked tracking item (gap, milestone, or issue) -- [ ] Report untracked TODOs - -### 6. Template Freshness - -- [ ] Compare `.ai/templates/` against actual recently-created documents -- [ ] Flag templates that no recent doc follows (may be outdated) - -## Output Format - -```markdown -# Doc Health Report — {YYYY-MM-DD} - -## Status Drift -- {finding with file references} - -## Stale Decisions -- {decision ID}: {reason it may be stale} - -## Orphaned Files -- {file path}: {why it appears orphaned} - -## Resolved Gaps -- {gap description}: {evidence it's resolved} - -## Untracked TODOs -- {file:line}: {TODO text} - -## Template Drift -- {template}: {issue} - -## Suggested Actions -1. {action} -2. {action} -``` - -## When to Fix vs Report - -- **Fix directly:** Simple status updates, removing dead links, marking decisions as `implemented` -- **Report only:** Anything that changes semantics, deletes content, or requires a judgment call diff --git a/.github/skills/draft-spec/SKILL.md b/.github/skills/draft-spec/SKILL.md deleted file mode 100644 index dee3558c..00000000 --- a/.github/skills/draft-spec/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ -# Skill: Draft Spec - -Write a milestone specification with clear acceptance criteria. - -## When to Use - -Milestone plan exists. User says: "Write spec for milestone X", "Draft M1" - -## Checklist - -1. **Gather context** - - [ ] Read epic spec for overall goals - - [ ] Read milestone plan for this milestone's place in sequence - - [ ] Read prior milestone specs/artifacts (if M2+) - - [ ] Check existing code for conventions and patterns - -2. **Write the spec** using milestone template - - [ ] **Goal:** 1-2 sentences — what this milestone achieves - - [ ] **Context:** What exists before this milestone - - [ ] **Acceptance Criteria:** Numbered, testable, pass/fail - - [ ] **Technical Notes:** Implementation hints, patterns to follow - - [ ] **Out of Scope:** What this milestone explicitly does NOT do - - [ ] **Dependencies:** What must exist before starting - -3. **Quality checks** - - [ ] Each AC is independently testable - - [ ] ACs don't overlap or contradict - - [ ] No vague criteria ("should be good", "well-tested") - - [ ] File paths and names follow project conventions - -4. **Save spec** - - [ ] Write to the project's milestone spec path - -5. **Optional tracker linkage** - - [ ] If the repo uses an external issue tracker, link the milestone spec according to repo-specific rules - -6. **User approval** - - [ ] Review spec with user - - [ ] Incorporate feedback - - [ ] Get explicit "approved" before proceeding - -## Output - -- Approved milestone spec in the project's milestone path - -## Next Step - -→ `start-milestone` to begin implementation diff --git a/.github/skills/patch/SKILL.md b/.github/skills/patch/SKILL.md deleted file mode 100644 index b5d7efa6..00000000 --- a/.github/skills/patch/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -description: Patch/chore skill for one-off fixes, tweaks, or maintenance tasks not tracked as epics or milestones. Can optionally be linked to a GitHub issue or another external tracker. -name: patch -when_to_use: | - - When a quick fix, UI tweak, or maintenance task is needed outside the epic/milestone workflow - - When responding to a bug, issue, or request tracked in GitHub Issues or another issue tracker -responsibilities: - - Read and understand the linked issue/task when one exists - - Create a descriptive branch (e.g., fix/..., patch/..., chore/...) - - Implement the change with focused commits - - Open a PR (prefer "Rebase and merge" to connect branch tip to main) - - Reference the issue/task in the PR and commit message when applicable - - Clean up the branch after merge -output: - - Linked PR and commit(s) referencing the issue/task when applicable - - Patch, fix, or maintenance change merged to main -invoked_by: - - planner agent (when a patch/chore/issue is requested) - - patcher/maintainer agent (if defined) ---- - -# Skill: Patch/Chore - -This skill enables the workflow to: -- Handle one-off fixes, UI tweaks, or maintenance tasks -- Link work to an issue or tracker item when one exists -- Keep the codebase healthy and responsive to small requests - -## Workflow -1. Read and understand the linked issue/task when one exists -2. Create a descriptive branch (fix/..., patch/..., chore/...) -3. Implement the change, run tests, stage files -4. 🛑 **STOP — show staged changes and proposed commit message. Wait for human to say "commit".** -5. Commit and push (only after explicit human approval) -6. Open a PR (prefer "Rebase and merge") -7. Reference the issue/task in PR and commit message when applicable -8. Merge and clean up the branch (only after human approval) -9. **Record learnings** — if this fix revealed a pattern, pitfall, or convention worth remembering: - - Append to `work/decisions.md` if a decision was made (use the standard format) - - Append to `work/agent-history/.md` with a brief note on what was learned - -## Example Triggers -- "Fix login button alignment (see GitHub Issue #123)" -- "Patch: update copyright year" -- "Chore: remove unused config" - -## Best Practices -- Keep the scope focused and the branch short-lived -- Reference the issue/task for traceability when one exists -- Use clear, conventional branch names diff --git a/.github/skills/plan-epic/SKILL.md b/.github/skills/plan-epic/SKILL.md deleted file mode 100644 index 5def388c..00000000 --- a/.github/skills/plan-epic/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ -# Skill: Plan Epic - -Scope, refine, and document a new epic. - -## When to Use - -User says: "Plan feature X", "Design the system for Y", "I need to build Z" - -## Checklist - -1. **Understand the request** - - [ ] What problem does this solve? - - [ ] Who benefits? - - [ ] What are the boundaries (in-scope / out-of-scope)? - -2. **Check existing context** - - [ ] Read the project's roadmap path for current epics and priorities - - [ ] Read the project's epic spec path for related or overlapping epics - - [ ] Check `work/gaps.md` for previously deferred work that fits - -3. **Clarify with user** (ask, don't guess) - - [ ] Confirm scope boundaries - - [ ] Identify key constraints (tech stack, timeline, dependencies) - - [ ] Agree on success criteria - -4. **Assign epic ID** - - [ ] Check the existing epic folders in the project's epic path for the highest existing E-xx number - - [ ] Assign next sequential number (e.g., if E-14 exists, use E-15) - - [ ] Epic numbering started at E-10; completed epics before E-10 are unnumbered - -5. **Write epic spec** - - [ ] Create the epic spec in the project's epic path using the epic template - - [ ] Set `**ID:** E-{NN}` in the spec header - - [ ] Fill in: goal, context, scope, constraints, success criteria - - [ ] List known risks and open questions - -6. **Optional tracker linkage** - - [ ] If the repo uses an external issue tracker, create or link the epic record according to repo-specific rules - -7. **Update roadmap** - - [ ] Add epic to the project's roadmap path with E-xx prefix and status `planning` - - [ ] Update any repo-specific epic index only if the repo actually uses one - -## Output - -- Epic specification in the project's epic path -- Updated project roadmap and any repo-specific epic index if applicable - -## Next Step - -→ `plan-milestones` to break the epic into sequenced milestones diff --git a/.github/skills/plan-milestones/SKILL.md b/.github/skills/plan-milestones/SKILL.md deleted file mode 100644 index 6e5fefec..00000000 --- a/.github/skills/plan-milestones/SKILL.md +++ /dev/null @@ -1,44 +0,0 @@ -# Skill: Plan Milestones - -Break an epic into a sequenced set of milestones. - -## When to Use - -Epic spec exists. User says: "Break this into milestones", "Plan the work for epic X" - -## Checklist - -1. **Read the epic spec** - - [ ] Read `work/epics//spec.md` - - [ ] Understand scope, constraints, success criteria - -2. **Decompose into milestones** - - [ ] Each milestone is independently shippable - - [ ] Each milestone has clear, testable acceptance criteria - - [ ] Dependencies flow forward (M1 before M2) - - [ ] Target 1-3 days of work per milestone - -3. **Sequence milestones** - - [ ] Order by dependency (foundational first) - - [ ] Group related work (don't scatter concerns) - - [ ] Identify any milestones that can be parallelized - -4. **Write milestone list** - - [ ] Add milestone table to epic spec or create standalone plan - - [ ] For each milestone: ID, title, 1-line summary, key dependencies - - [ ] Naming: `m---` (e.g., `m-E12-01-query-schema`) - - [ ] The `` prefix comes from the epic's E-xx ID (e.g., E-12 → `m-E12-01`) - -5. **Confirm with user** - - [ ] Review milestone sequence together - - [ ] Agree on priority and order - - [ ] Identify any scope adjustments - -## Output - -- Milestone plan (table in epic spec or separate doc) -- Milestone IDs ready for spec drafting - -## Next Step - -→ `draft-spec` for each milestone (start with M1) diff --git a/.github/skills/quality-score/SKILL.md b/.github/skills/quality-score/SKILL.md deleted file mode 100644 index 02d05736..00000000 --- a/.github/skills/quality-score/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -description: Assess and maintain per-surface quality scorecards. Tracks test coverage, tech debt, doc freshness, and convention compliance. -name: quality-score -when_to_use: | - - After wrapping a milestone (as part of review) - - When the user asks "how healthy is surface X?" - - Periodically to track quality trends -responsibilities: - - Compute or estimate test coverage per surface - - Inventory known tech debt and unresolved TODOs - - Check doc freshness (last meaningful update vs last code change) - - Verify convention compliance (naming, structure, patterns) - - Produce a scorecard and update the quality tracking file -output: - - Quality scorecard (Markdown) per surface - - Updated quality tracking file at the path defined by the repo -invoked_by: - - reviewer agent (during wrap-milestone or on request) - - any agent when the user asks about quality ---- - -# Skill: Quality Score - -Assess and record quality metrics per project surface. - -## Surfaces - -A "surface" is a deployable or testable unit — e.g., `Core`, `API`, `Sim.Core`, `UI`. -The repo defines its surfaces; the framework defines how to score them. - -## Checklist - -### 1. Test Coverage - -- [ ] Run tests with coverage enabled (or estimate from test file inventory) -- [ ] Record: total tests, passing, coverage % (line or branch) -- [ ] Note any untested public APIs or critical paths - -### 2. Tech Debt Inventory - -- [ ] Count `TODO`, `FIXME`, `HACK` comments in the surface -- [ ] Count items in `work/gaps.md` targeting this surface -- [ ] Note any known workarounds or compatibility shims - -### 3. Doc Freshness - -- [ ] Check `docs/` files related to this surface -- [ ] Compare last meaningful doc update date vs last code change date -- [ ] Flag docs that are > 30 days stale relative to code - -### 4. Convention Compliance - -- [ ] Spot-check naming (fields, methods, files) against project conventions -- [ ] Check for deprecated patterns the project has moved away from -- [ ] Verify JSON schema compliance (camelCase, no deprecated fields) - -### 5. Build Health - -- [ ] Build succeeds with no warnings (or note warning count) -- [ ] No analyzer suppressions without justification - -## Scorecard Format - -Use the `quality-scorecard` template. Store at `work/quality/{surface}.md` or wherever the repo configures. - -## Trends - -When updating a scorecard, preserve the previous snapshot in a `## History` section so trends are visible. Keep the last 5 snapshots; archive older ones. diff --git a/.github/skills/release/SKILL.md b/.github/skills/release/SKILL.md deleted file mode 100644 index b9f18643..00000000 --- a/.github/skills/release/SKILL.md +++ /dev/null @@ -1,52 +0,0 @@ -# Skill: Release - -Tag a release, update changelog, and publish. - -## When to Use - -Epic is complete and merged to main. User says: "Release v1.2", "Tag a release", "Publish" - -## Checklist - -1. **Pre-release checks** - - [ ] On `main` branch - - [ ] All tests pass - - [ ] Build is green - - [ ] No uncommitted changes - -2. **Determine version** - - [ ] Check current version (latest git tag) - - [ ] Apply semantic versioning: - - `MAJOR` — breaking changes - - `MINOR` — new features, backward compatible - - `PATCH` — bug fixes only - - [ ] Confirm version with user - -3. **Update changelog** - - [ ] Add release section to `CHANGELOG.md` - - [ ] Group changes: Added, Changed, Fixed, Removed - - [ ] Reference milestone/epic for context - - [ ] Stage changelog, show diff - - [ ] 🛑 **STOP — wait for human to say "commit"** - - [ ] Commit changelog: `docs: update changelog for vX.Y.Z` - -4. **Create tag** (only after human approval) - - [ ] 🛑 Confirm with human: "Tag as vX.Y.Z and push?" - - [ ] `git tag -a vX.Y.Z -m "Release vX.Y.Z: "` - - [ ] Push tag: `git push origin vX.Y.Z` - - [ ] Mirror to GHE: `git push ghe vX.Y.Z` - -5. **Post-release** - - [ ] Update the project's roadmap path — mark epic as `released` - - [ ] Verify deployment (if CI/CD auto-deploys on tag) - - [ ] Run health checks - - [ ] **Record learnings** — append to `work/agent-history/deployer.md`: - - Release process issues or improvements discovered - - Infrastructure or pipeline patterns worth remembering - - [ ] If any deployment decisions were made, append to `work/decisions.md` - -## Output - -- Git tag `vX.Y.Z` -- Updated `CHANGELOG.md` -- Updated project roadmap diff --git a/.github/skills/review-code/SKILL.md b/.github/skills/review-code/SKILL.md deleted file mode 100644 index 0186ffa7..00000000 --- a/.github/skills/review-code/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ -# Skill: Review Code - -Review changes for correctness, quality, and completeness. - -## When to Use - -Code changes are ready for review. User says: "Review this", "Check my changes", "Review PR" - -## Checklist - -1. **Understand the scope** - - [ ] What milestone or task do these changes address? - - [ ] Read the milestone spec / acceptance criteria - - [ ] Read the tracking doc for implementation notes - -2. **Review the diff** - - [ ] Check changed files (`git diff --staged` or PR diff) - - [ ] Verify each change serves the stated goal - - [ ] Flag unrelated changes - -3. **Correctness** - - [ ] Logic is correct for stated requirements - - [ ] Edge cases are handled (null, empty, boundary) - - [ ] Error handling is adequate - - [ ] No off-by-one errors, race conditions, or resource leaks - -4. **Tests** - - [ ] Tests exist for each acceptance criterion - - [ ] Tests are deterministic - - [ ] Tests cover both happy path and edge cases - - [ ] No tests were removed without justification - -5. **Conventions** - - [ ] Naming follows project conventions - - [ ] File placement follows project structure - - [ ] No hardcoded values that should be configurable - - [ ] No secrets or PII - -6. **Documentation** - - [ ] README updated if public API changed - - [ ] Inline comments for non-obvious logic - - [ ] Tracking doc reflects implementation - -7. **Verdict** - - [ ] **Approve** — changes are correct and complete - - [ ] **Request changes** — list specific issues with file/line references - - [ ] **Questions** — need clarification before deciding - -## Output - -Review summary with: -- Verdict (approve / request changes) -- Specific findings (file, line, issue, suggestion) -- Overall assessment diff --git a/.github/skills/start-milestone/SKILL.md b/.github/skills/start-milestone/SKILL.md deleted file mode 100644 index a561ee7a..00000000 --- a/.github/skills/start-milestone/SKILL.md +++ /dev/null @@ -1,82 +0,0 @@ -# Skill: Start Milestone - -Set up and begin implementing a milestone. - -## When to Use - -Approved milestone spec exists. User says: "Start milestone X", "Implement M1" - -## Checklist - -1. **Preflight** - - [ ] Read the milestone spec from the project's milestone path - - [ ] Verify spec is approved (user confirmed) - - [ ] Check build passes (`dotnet build` / `npm run build` / etc.) - - [ ] Check existing tests pass - - [ ] Read prior milestone code if building on previous work - -2. **Update milestone status** - - [ ] Update the spec status to `in-progress` - - [ ] Reconcile milestone status across all repo-owned status surfaces for that epic: milestone spec, milestone tracking doc, epic milestone table, roadmap, epic roadmap/index, and `CLAUDE.md` current work - - [ ] If the repo uses an external issue tracker, sync status according to repo-specific rules - -3. **Branch setup** - - [ ] If milestone belongs to an epic: ensure epic integration branch exists (`epic/E-{NN}-`), create from `main` if missing, push to origin - - [ ] Create or switch to milestone branch: `milestone/` (branch from epic branch if applicable, otherwise from `main`) - - [ ] Verify milestone branch is up to date with its base - -4. **Create tracking doc** - - [ ] Create the milestone tracking doc in the project's tracking path using the tracking template - - [ ] List all acceptance criteria as unchecked boxes - - [ ] Note start date and initial context - - [ ] If this milestone starts on a continuation branch, explicitly close any previously finished milestone statuses left as `in-progress` / `pending` on the same branch - -5. **Update CLAUDE.md current work section** - - [ ] Update the `## Current Work` section in `CLAUDE.md` with: - - Active epic name and spec path - - Current milestone ID, title, and status - - Current branch name - - [ ] If the section doesn't exist, add it at the end of the file - -6. **Plan implementation phases** - - [ ] Group ACs into logical phases (1-4 phases typical) - - [ ] Identify test strategy for each phase - - [ ] Note implementation order - -7. **Begin implementation** using `tdd-cycle` - - [ ] Start with Phase 1 - - [ ] For each AC: write tests → implement → verify - - [ ] Update tracking doc after each AC is complete - -8. **Completion check** - - [ ] All ACs checked in tracking doc - - [ ] All tests passing - - [ ] Build green - - [ ] Stage changes (`git add`) - - [ ] Show staged diff summary to user - - [ ] Report: "Implementation complete. N tests passing, build green. Here are the staged changes:" - - [ ] 🛑 **STOP — Do NOT commit. Wait for human to say "commit".** - - [ ] **Record learnings** — append to `work/agent-history/builder.md`: - - Patterns that worked (testing approaches, code organization) - - Pitfalls encountered (build issues, test flakiness, API quirks) - - Conventions established (naming, structure decisions) - - [ ] If any decisions were made during implementation, append to `work/decisions.md` - -9. **Commit and merge** (ONLY after human explicitly says "commit") - - [ ] 🛑 Verify human said "commit" / "push" / "go ahead and commit" — not just "continue" or "ok" - - [ ] Commit on milestone branch with descriptive message - - [ ] 🛑 **STOP — ask before pushing.** "Push to origin?" - - [ ] Push milestone branch - - [ ] 🛑 **STOP — ask before merging.** "Merge into epic branch?" - - [ ] If epic branch exists: merge milestone branch into epic branch (`--no-ff`), push epic branch - - [ ] If standalone: milestone branch is ready for PR to `main` - -## Output - -- Implemented code + tests (staged, not committed) -- Tracking doc with all ACs checked -- Updated README/docs if applicable - -## Next Step - -→ `review-code` for code review, then `wrap-milestone` diff --git a/.github/skills/tdd-cycle/SKILL.md b/.github/skills/tdd-cycle/SKILL.md deleted file mode 100644 index f8671a55..00000000 --- a/.github/skills/tdd-cycle/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ -# Skill: TDD Cycle - -Test-driven development workflow for implementing acceptance criteria. - -## When to Use - -During milestone implementation. For each acceptance criterion or feature unit. - -## Checklist - -### RED — Write failing test - -- [ ] Write test(s) that describe the expected behavior -- [ ] Test names follow convention: `MethodName_Scenario_ExpectedResult` -- [ ] Use project's test framework (xUnit, Jest, pytest, etc.) -- [ ] Use mocks/stubs for external dependencies -- [ ] Run tests → confirm they **FAIL** for the right reason - -### GREEN — Make it pass - -- [ ] Write the **minimum** code to make the test pass -- [ ] Don't add features the test doesn't require -- [ ] Run tests → confirm they **PASS** -- [ ] Check no other tests broke - -### REFACTOR — Clean up - -- [ ] Remove duplication -- [ ] Improve naming -- [ ] Extract methods/classes if needed -- [ ] Run tests → confirm still **GREEN** - -### Update Tracking - -- [ ] Check off the acceptance criterion in tracking doc -- [ ] Note any decisions or deviations - -## Anti-patterns - -- Writing code before tests -- Writing tests that can't fail -- Skipping the refactor step -- Testing implementation details instead of behavior -- Tests that depend on execution order - -## Test Quality Checks - -- [ ] Tests are deterministic (no randomness, no clock, no network) -- [ ] Tests are independent (no shared mutable state) -- [ ] Tests cover edge cases (null, empty, boundary values) -- [ ] Test names explain what is being tested - -## Branch Coverage Audit (before declaring done) - -Every TDD cycle ends with a final pass that confirms every reachable branch in the implementation has at least one test. This is a **hard rule** — see `.ai/agents/builder.md` Constraints. - -- [ ] Open each new or changed source file and walk it line-by-line -- [ ] For every `if`/`else`/`switch`/`catch`/`?:`/early-return, identify which test exercises each side -- [ ] If a branch has no test, write one. Defensive paths (guards, exception catches, malformed-input handlers) count as reachable — if it ships, it gets a test -- [ ] If a helper is private and the branch is hard to reach via the public API, expose it to tests using the language's friend-assembly / package-private mechanism (e.g., `internal` + `InternalsVisibleTo` in C#, `pub(crate)` in Rust, `_internal` convention or `__all__` in Python, package-private in Java/Go) and write a direct test -- [ ] Genuinely unreachable branches (e.g., a defensive `null` check on a value the type system guarantees non-null) must be documented in the milestone spec under a "Coverage notes" section with the reason -- [ ] **Do not declare "every branch covered" without performing the audit.** Saying it is not the same as proving it. The audit happens before the commit-approval prompt, not after the human asks. diff --git a/.github/skills/ui-debug/SKILL.md b/.github/skills/ui-debug/SKILL.md deleted file mode 100644 index 097259af..00000000 --- a/.github/skills/ui-debug/SKILL.md +++ /dev/null @@ -1,13 +0,0 @@ -# Skill: ui-debug - -Diagnose UI issues quickly and reproducibly. - -**Use when:** UI behavior is incorrect, flaky, or unclear. - -## Checklist - -- [ ] Reproduce with the smallest possible scenario -- [ ] Check for an existing Playwright test — run or update it before manual fixes -- [ ] Prefer Playwright tests for deterministic reproduction -- [ ] If updating snapshots, note why and keep diffs minimal -- [ ] Avoid external network calls; mock or stub where needed diff --git a/.github/skills/wrap-milestone/SKILL.md b/.github/skills/wrap-milestone/SKILL.md deleted file mode 100644 index 3dce244e..00000000 --- a/.github/skills/wrap-milestone/SKILL.md +++ /dev/null @@ -1,75 +0,0 @@ -# Skill: Wrap Milestone - -Complete a milestone, write summary, and prepare for merge. - -## When to Use - -All acceptance criteria met, tests passing, build green. User says: "Wrap milestone X", "Finish M1" - -## Checklist - -1. **Verify completion** - - [ ] Read milestone spec — check every AC is implemented - - [ ] Read tracking doc — all ACs checked - - [ ] Run full test suite — all pass - - [ ] Build is green - -2. **Final review** - - [ ] No TODO comments left behind (unless intentional and documented) - - [ ] No debug code or temporary workarounds - - [ ] Documentation is up to date - -3. **Update tracking doc** - - [ ] Mark milestone as complete with final date - - [ ] Add final test count and build status - - [ ] Reconcile completion status across all repo-owned status surfaces for that epic: milestone spec, milestone tracking doc, epic milestone table, roadmap, epic roadmap/index, and `CLAUDE.md` current work - -4. **Optional tracker wrap-up** - - [ ] If the repo uses an external issue tracker, close or update the linked milestone/epic records according to repo-specific rules - -5. **Note deferred work** - - [ ] Any deferred items → `work/gaps.md` - -6. **Update CLAUDE.md current work section** - - [ ] Update the `## Current Work` section in `CLAUDE.md`: - - Mark current milestone as complete - - If there's a next milestone in the epic, set it as upcoming - - If this was the last milestone, note epic as complete - - [ ] This ensures the next conversation starts with accurate context - -7. **Prepare merge** - - [ ] Ensure all changes are staged - - [ ] Show staged diff summary (`git diff --staged --stat`) - - [ ] Prepare commit message (conventional format) - - [ ] 🛑 **STOP — present staged changes and commit message to user.** - - [ ] Say: "Ready to commit and merge. Here's what will be committed: [summary]. Commit message: [message]. Shall I commit?" - - [ ] **Wait for human to explicitly say "commit" before proceeding.** - -8. **After user says "commit"** (NOT "ok", NOT "continue" — must say "commit") - - [ ] Commit with agreed message - - [ ] 🛑 **STOP — ask: "Push and merge to [branch]?"** - - [ ] Merge to base branch (or create PR) - - [ ] Update the project's roadmap path if the milestone was the last in an epic - - [ ] Move the completed epic folder only if the repo actually uses a completed-epics archive path - - [ ] Update any repo-specific epic index only if the repo actually uses one - -9. **Record learnings** (memory write-back) - - [ ] Append any new architectural or technical decisions to `work/decisions.md` using this format: - ```markdown - ## D-YYYY-MM-DD-NNN: - **Status:** active - **Context:** - **Decision:** - **Consequences:** - ``` - - [ ] Append implementation learnings to the current agent's history file (`work/agent-history/.md`): - - Patterns that worked well - - Pitfalls encountered and how they were resolved - - Project conventions discovered or established - - [ ] Keep entries concise (2-5 lines each). If the history file exceeds ~200 lines, summarize older entries. - -## Output - -- Committed and merged code (after approval) -- Updated tracking doc (final status) -- Updated `gaps.md` (if deferred work found) diff --git a/.gitignore b/.gitignore index 20f163c8..cecaa389 100644 --- a/.gitignore +++ b/.gitignore @@ -84,3 +84,8 @@ coverage/ # Azure Functions local local.settings.json .scratch/ + +# Generated assistant adapter surfaces (rebuild locally with `bash .ai/sync.sh`) +.github/copilot-instructions.md +.github/skills/ +.claude/rules/ai-framework.md