haac-aikit 0.1.1 → 0.7.2

package/catalog/hooks/check-pattern-violations.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Telemetry hook: pattern-checks just-written files against rules in
+# .claude/aikit-rules.json and logs violations.
+# Fires on PostToolUse(Edit|Write).
+#
+# Output: appends one JSON line per violation to .aikit/events.jsonl.
+# Schema: {"ts":"<iso>","event":"violation","rule_id":"<id>","file":"<path>","severity":"<level>","line":<n>}
+#
+# Read-only and non-blocking. Never fails the tool call.
+
+set -euo pipefail
+
+INPUT="$(cat)"
+LOG_DIR=".aikit"
+LOG_FILE="$LOG_DIR/events.jsonl"
+RULES_FILE=".claude/aikit-rules.json"
+
+mkdir -p "$LOG_DIR" 2>/dev/null || exit 0
+
+# Bail if there are no rules to check.
+[[ ! -f "$RULES_FILE" ]] && { echo '{"decision":"approve"}'; exit 0; }
+
+# Extract the file_path from the tool input.
+FILE_PATH="$(echo "$INPUT" | python3 -c "import sys,json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('file_path','') or d.get('path',''))
+except Exception:
+    pass" 2>/dev/null || echo "")"
+
+[[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]] && { echo '{"decision":"approve"}'; exit 0; }
+
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Use python to parse JSON rules + apply globs + scan for patterns. Bash glob
+# matching is too limited (no exclude support, no `**`).
+HOOK_FILE_PATH="$FILE_PATH" HOOK_RULES_PATH="$RULES_FILE" HOOK_LOG_PATH="$LOG_FILE" HOOK_TS="$TS" \
+python3 <<'PY' 2>/dev/null || true
+import json, re, os, sys
+file_path = os.environ["HOOK_FILE_PATH"]
+rules_path = os.environ["HOOK_RULES_PATH"]
+log_path = os.environ["HOOK_LOG_PATH"]
+ts = os.environ["HOOK_TS"]
+try:
+    with open(rules_path, "r", encoding="utf-8") as f:
+        cfg = json.load(f)
+except Exception:
+    sys.exit(0)
+
+def glob_to_regex(pattern: str) -> str:
+    # Custom translator because Python 3.9's pathlib doesn't handle ** recursion
+    # and fnmatch treats ** as a single segment.
+    out = []
+    i = 0
+    while i < len(pattern):
+        c = pattern[i]
+        if c == "*":
+            if i + 1 < len(pattern) and pattern[i + 1] == "*":
+                if i + 2 < len(pattern) and pattern[i + 2] == "/":
+                    out.append(r"(?:[^/]+/)*")  # zero-or-more directory segments
+                    i += 3
+                    continue
+                out.append(".*")
+                i += 2
+                continue
+            out.append(r"[^/]*")
+            i += 1
+        elif c == "?":
+            out.append(r"[^/]")
+            i += 1
+        elif c in ".+()[]{}|^$\\":
+            out.append("\\" + c)
+            i += 1
+        else:
+            out.append(c)
+            i += 1
+    return "^" + "".join(out) + "$"
+
+def glob_match(path: str, patterns) -> bool:
+    for p in patterns:
+        rx = re.compile(glob_to_regex(p))
+        if rx.match(path):
+            return True
+    return False
+
+try:
+    with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+        content = f.read()
+except Exception:
+    sys.exit(0)
+
+events = []
+for rule in cfg.get("rules", []):
+    rid = rule.get("id") or ""
+    pat = rule.get("pattern")
+    if not rid or not pat:
+        continue
+    includes = rule.get("fileGlobs") or ["**/*"]
+    excludes = rule.get("exclude") or []
+    if not glob_match(file_path, includes):
+        continue
+    if excludes and glob_match(file_path, excludes):
+        continue
+    try:
+        rx = re.compile(pat, re.MULTILINE)
+    except re.error as compile_err:
+        events.append({
+            "ts": ts,
+            "event": "rule_compile_error",
+            "rule_id": rid,
+            "pattern": pat[:200],
+            "error": str(compile_err)[:200],
+        })
+        continue
+    for m in rx.finditer(content):
+        line = content.count("\n", 0, m.start()) + 1
+        events.append({
+            "ts": ts,
+            "event": "violation",
+            "rule_id": rid,
+            "file": file_path,
+            "severity": rule.get("severity", "warn"),
+            "line": line,
+        })
+
+if events:
+    try:
+        os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
+        with open(log_path, "a", encoding="utf-8") as f:
+            for e in events:
+                f.write(json.dumps(e, separators=(",", ":")) + "\n")
+    except Exception:
+        pass
+PY
+
+# Always approve — this hook only observes.
+echo '{"decision":"approve"}'

package/catalog/hooks/hooks.json

@@ -40,6 +40,44 @@
             "type": "command",
             "command": "bash .claude/hooks/format-on-save.sh",
             "description": "Auto-format after file write"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/check-pattern-violations.sh",
+            "description": "Telemetry: pattern-check just-written file against .claude/aikit-rules.json"
+          }
+        ]
+      }
+    ],
+    "InstructionsLoaded": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/log-rule-event.sh",
+            "description": "Telemetry: record which rule IDs loaded this session"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/judge-rule-compliance.sh",
+            "description": "Telemetry: opt-in LLM judge of rule compliance (set AIKIT_JUDGE=1)"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/judge-rule-compliance.sh",
+            "description": "Telemetry: opt-in LLM judge of rule compliance (set AIKIT_JUDGE=1)"
           }
         ]
       }

package/catalog/hooks/judge-rule-compliance.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# Telemetry hook: opt-in LLM judge that verdicts whether the assistant's last
+# turn cited / violated / ignored each loaded rule.
+# Fires on Stop and SubagentStop.
+#
+# Output: appends one JSON line per rule verdict to .aikit/events.jsonl.
+# Schema: {"ts":"<iso>","event":"cited"|"judged_violation","rule_id":"<id>","verdict":"<text>"}
+#
+# Activation:
+#   - Set AIKIT_JUDGE=1 (otherwise the hook exits immediately, free).
+#   - Set ANTHROPIC_API_KEY (otherwise the hook exits silently).
+# Cost: ~$0.001/turn with claude-haiku-4-5. Disabled by default for that reason.
+#
+# Read-only and non-blocking. Never fails the parent tool call.
+
+set -uo pipefail
+
+INPUT="$(cat)"
+LOG_DIR=".aikit"
+LOG_FILE="$LOG_DIR/events.jsonl"
+MODEL="${AIKIT_JUDGE_MODEL:-claude-haiku-4-5-20251001}"
+
+# Always echo approve at the end, even on early exit.
+trap 'echo "{\"decision\":\"approve\"}"' EXIT
+
+# Cheap exits before any expensive work.
+[[ "${AIKIT_JUDGE:-0}" != "1" ]] && exit 0
+[[ -z "${ANTHROPIC_API_KEY:-}" ]] && exit 0
+command -v curl >/dev/null 2>&1 || exit 0
+mkdir -p "$LOG_DIR" 2>/dev/null || exit 0
+
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Build the judge call entirely in python so JSON escaping is correct. The
+# script reads the hook input (assistant transcript) from $HOOK_INPUT, scans
+# the project's rule files for declared IDs, and asks Haiku for a verdict.
+HOOK_INPUT="$INPUT" HOOK_LOG="$LOG_FILE" HOOK_TS="$TS" HOOK_MODEL="$MODEL" \
+python3 <<'PY' 2>/dev/null || true
+import json, os, re, sys, urllib.request, urllib.error
+
+api_key = os.environ.get("ANTHROPIC_API_KEY", "")
+if not api_key:
+    sys.exit(0)
+
+raw = os.environ.get("HOOK_INPUT", "")
+log_path = os.environ["HOOK_LOG"]
+ts = os.environ["HOOK_TS"]
+model = os.environ["HOOK_MODEL"]
+
+try:
+    payload = json.loads(raw) if raw else {}
+except Exception:
+    payload = {}
+
+# Try to extract the assistant's last response. Hook input shape varies across
+# Claude Code versions; handle a few likely fields.
+transcript = ""
+for key in ("assistant_message", "last_response", "transcript", "messages"):
+    val = payload.get(key)
+    if isinstance(val, str):
+        transcript = val
+        break
+    if isinstance(val, list) and val:
+        last = val[-1]
+        if isinstance(last, dict):
+            transcript = str(last.get("content") or last.get("text") or "")
+        else:
+            transcript = str(last)
+        break
+
+if not transcript or len(transcript) < 20:
+    sys.exit(0)
+
+# Cap transcript size to keep the judge prompt cheap.
+if len(transcript) > 8000:
+    transcript = transcript[:8000] + "\n...[truncated]"
+
+# Collect declared rule IDs from project rule files.
+id_rx = re.compile(r"<!--\s*id:\s*([a-zA-Z][a-zA-Z0-9_-]*\.[a-zA-Z0-9._-]+)(?:\s+[a-zA-Z][a-zA-Z0-9_-]*=[^>\s]+)*\s*-->")
+rules = {}  # id -> surrounding line for context
+candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"]
+rules_dir = ".claude/rules"
+if os.path.isdir(rules_dir):
+    for f in os.listdir(rules_dir):
+        if f.endswith(".md"):
+            candidates.append(os.path.join(rules_dir, f))
+
+for path in candidates:
+    if not os.path.isfile(path):
+        continue
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            content = fh.read()
+    except Exception:
+        continue
+    for line in content.splitlines():
+        m = id_rx.search(line)
+        if not m:
+            continue
+        rid = m.group(1)
+        # Strip the comment to get the rule text in human-readable form.
+        text = id_rx.sub("", line).strip(" -*\t")
+        if rid and text and rid not in rules:
+            rules[rid] = text[:240]
+
+if not rules:
+    sys.exit(0)
+
+# Construct judge prompt. Keep it tight — Haiku rewards specificity.
+rules_block = "\n".join(f"- {rid}: {txt}" for rid, txt in rules.items())
+prompt = (
+    "You are a precise auditor. Given the assistant's last response and a list "
+    "of project rules, decide for each rule whether the response CITED it "
+    "(referenced it explicitly), VIOLATED it (acted against it), or was "
+    "IRRELEVANT (the rule didn't apply this turn). Respond with JSON only.\n\n"
+    f"RULES:\n{rules_block}\n\n"
+    f"ASSISTANT RESPONSE:\n{transcript}\n\n"
+    'Output JSON exactly: {"verdicts":[{"rule_id":"...","status":"cited|violated|irrelevant","reason":"<10 words"}]}'
+)
+
+req = urllib.request.Request(
+    "https://api.anthropic.com/v1/messages",
+    data=json.dumps({
+        "model": model,
+        "max_tokens": 1024,
+        "messages": [{"role": "user", "content": prompt}],
+    }).encode("utf-8"),
+    headers={
+        "Content-Type": "application/json",
+        "x-api-key": api_key,
+        "anthropic-version": "2023-06-01",
+    },
+)
+
+def log_error(reason):
+    # Errors land in a sibling log so the user (who explicitly opted in via
+    # AIKIT_JUDGE=1 and is paying for verdicts) can see why a turn produced
+    # nothing. Stays out of events.jsonl to keep the rule-event stream clean.
+    try:
+        err_path = os.path.join(os.path.dirname(log_path) or ".", "judge-errors.log")
+        os.makedirs(os.path.dirname(err_path) or ".", exist_ok=True)
+        with open(err_path, "a", encoding="utf-8") as eh:
+            eh.write(f"{ts}  {reason}\n")
+    except Exception:
+        pass
+
+try:
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        body = json.loads(resp.read().decode("utf-8"))
+except urllib.error.HTTPError as e:
+    log_error(f"http {e.code}: {e.reason}")
+    sys.exit(0)
+except urllib.error.URLError as e:
+    log_error(f"url-error: {e.reason}")
+    sys.exit(0)
+except (TimeoutError, json.JSONDecodeError) as e:
+    log_error(f"transport: {type(e).__name__}: {e}")
+    sys.exit(0)
+
+# Extract the model's text content.
+text_chunks = [c.get("text", "") for c in body.get("content", []) if c.get("type") == "text"]
+verdict_text = "\n".join(text_chunks).strip()
+
+# Pull out the first {...} JSON object (Haiku usually emits clean JSON, but be defensive).
+match = re.search(r"\{.*\}", verdict_text, re.DOTALL)
+if not match:
+    log_error(f"no JSON object in model response (len={len(verdict_text)})")
+    sys.exit(0)
+try:
+    verdicts = json.loads(match.group(0)).get("verdicts", [])
+except Exception as e:
+    log_error(f"verdicts json parse failed: {e}")
+    sys.exit(0)
+
+# Append events. cited → "cited", violated → "judged_violation", irrelevant → skip.
+events = []
+for v in verdicts:
+    rid = v.get("rule_id")
+    status = v.get("status")
+    if not rid or status not in {"cited", "violated"}:
+        continue
+    events.append({
+        "ts": ts,
+        "event": "cited" if status == "cited" else "judged_violation",
+        "rule_id": rid,
+        "verdict": (v.get("reason") or "")[:200],
+    })
+
+if events:
+    try:
+        os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
+        with open(log_path, "a", encoding="utf-8") as fh:
+            for e in events:
+                fh.write(json.dumps(e, separators=(",", ":")) + "\n")
+    except Exception:
+        pass
+PY

package/catalog/hooks/log-rule-event.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Telemetry hook: records when instruction files load and which rule IDs they contain.
+# Fires on InstructionsLoaded.
+#
+# Output: appends one JSON line per loaded rule to .aikit/events.jsonl.
+# Schema: {"ts":"<iso>","event":"loaded","rule_id":"<id>","source":"<path>"}
+#
+# This hook is read-only and never blocks. If anything fails it exits silently
+# so it can never break a Claude Code session.
+
+set -euo pipefail
+
+INPUT="$(cat)"
+LOG_DIR=".aikit"
+LOG_FILE="$LOG_DIR/events.jsonl"
+
+# Bail early if we can't even create the log dir (read-only fs, etc.).
+mkdir -p "$LOG_DIR" 2>/dev/null || { echo '{"decision":"approve"}'; exit 0; }
+
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Do all work inside python so file paths with quotes/backslashes can't break
+# the JSONL output (json.dumps escapes them safely).
+HOOK_INPUT="$INPUT" HOOK_LOG="$LOG_FILE" HOOK_TS="$TS" \
+python3 <<'PY' 2>/dev/null || true
+import json, os, re
+try:
+    payload = json.loads(os.environ.get("HOOK_INPUT", "") or "{}")
+    if not isinstance(payload, dict):
+        payload = {}
+except Exception:
+    payload = {}
+
+candidates = []
+for key in ("files", "paths", "instructionFiles", "loaded", "memory"):
+    val = payload.get(key)
+    if isinstance(val, list):
+        candidates.extend(str(v) for v in val if v)
+    elif isinstance(val, str):
+        candidates.append(val)
+# Always probe the standard memory file locations even if not echoed back.
+for default in ("AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"):
+    candidates.append(default)
+
+# Dedupe while preserving order.
+seen = set()
+files = [c for c in candidates if not (c in seen or seen.add(c))]
+
+# Match a dotted-slug rule ID, starting with a letter so docstring examples
+# like <!-- id: ... --> don't produce phantom events. Allows optional
+# space-separated key=value metadata between the ID and the closing -->.
+id_rx = re.compile(r"<!--\s*id:\s*([a-zA-Z][a-zA-Z0-9_-]*\.[a-zA-Z0-9._-]+)(?:\s+[a-zA-Z][a-zA-Z0-9_-]*=[^>\s]+)*\s*-->")
+ts = os.environ["HOOK_TS"]
+log_path = os.environ["HOOK_LOG"]
+
+events = []
+for path in files:
+    if not os.path.isfile(path):
+        continue
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            content = fh.read()
+    except Exception:
+        continue
+    for match in id_rx.finditer(content):
+        rule_id = match.group(1)
+        if rule_id:
+            events.append({"ts": ts, "event": "loaded", "rule_id": rule_id, "source": path})
+
+if events:
+    try:
+        with open(log_path, "a", encoding="utf-8") as fh:
+            for e in events:
+                fh.write(json.dumps(e, separators=(",", ":")) + "\n")
+    except Exception:
+        pass
+PY
+
+# Always approve — this hook only observes.
+echo '{"decision":"approve"}'

package/catalog/rules/AGENTS.md.tmpl

@@ -27,20 +27,41 @@ TODO: 3-5 bullets on where things live.
 TODO: How to run a single test; framework quirks.
 
 ## Commit & PR conventions
-- Conventional commits: `type(scope): description`
-- Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`
-- PR title < 70 characters; body: Summary + Test Plan.
-- Never force-push to `main`/`master`/`develop`.
+<!-- Rule IDs (the `<!-- id: ... -->` comments below) are used by
+     `aikit doctor --rules` to track which rules fire and which are followed.
+     They cost zero context tokens (HTML comments are stripped before injection).
+     Optional metadata after the ID:
+       emphasis=high     prefix with **bold** in dialect translators
+       paths=glob,glob   restrict to matching files (Cursor `globs:`, Claude `paths:`)
+     Add IDs to your own rules to opt them into observability + translation. -->
+- <!-- id: commit.conventional-commits --> Conventional commits: `type(scope): description`
+- <!-- id: commit.types --> Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`
+- <!-- id: pr.title-under-70 --> PR title < 70 characters; body: Summary + Test Plan.
+- <!-- id: git.no-force-push-protected emphasis=high --> Never force-push to `main`/`master`/`develop`.
 
 ## Security
-Never read, write, or commit:
+<!-- id: security.no-sensitive-files emphasis=high --> Never read, write, or commit:
 - `.env*`, `secrets/`, `.ssh/`, `.aws/`, `*.pem`, `id_rsa*`
 
-Never force-push to `main`/`master`/`develop`.
+<!-- id: git.no-force-push-protected emphasis=high --> Never force-push to `main`/`master`/`develop`.
 
 TODO: Project-specific security notes.
 
 ## Gotchas
-<!-- High-signal section. Add things the agent repeatedly gets wrong. -->
+<!-- High-signal section. Add things the agent repeatedly gets wrong.
+     Tip: prefix the most load-bearing rules with `IMPORTANT:` or `YOU MUST` —
+     Anthropic guidance says emphasis tokens improve adherence noticeably.
+     HTML block comments like this one are stripped before injection, so they
+     cost zero context tokens. -->
 TODO
+
+## When compacting
+<!-- Tells Claude what to preserve when /compact runs. The project-root
+     CLAUDE.md / AGENTS.md is re-injected after compaction; nested files are
+     not. Use this block to lock in must-keep context. -->
+Always preserve: the full list of files modified this session, any failing test names + error messages, and the current task being worked on.
+
+## Further reading
+- `docs/claude-md-reference.md` — Anthropic 2026 reference for CLAUDE.md / memory / `.claude/rules/` (shipped by `aikit` when `claude` is selected at scope ≥ standard).
+- `.claude/rules/` — drop topic-scoped or path-scoped rule files here (see the example shipped with this kit). Path-scoped rules load only when Claude reads matching files, saving context.
 <!-- END:haac-aikit -->

package/catalog/rules/aikit-rules.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://raw.githubusercontent.com/Hamad-Center/haac-aikit/main/schema/aikit-rules.schema.json",
+  "version": 1,
+  "comment": "Maps rule IDs (in AGENTS.md / .claude/rules/*.md) to machine-checkable patterns. The PostToolUse hook reads this to detect violations in just-written files. Pattern-checkable rules are a SUBSET of all rules — many rules can only be observed (loaded/cited) but not auto-validated. Add your own; remove what you don't want.",
+  "rules": [
+    {
+      "id": "code-style.no-console-log",
+      "title": "No console.log in production code",
+      "pattern": "(?<!//\\s)console\\.log\\(",
+      "fileGlobs": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx"],
+      "exclude": ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"],
+      "severity": "warn"
+    },
+    {
+      "id": "code-style.no-default-export",
+      "title": "Use named exports, not default",
+      "pattern": "^\\s*export\\s+default\\b",
+      "fileGlobs": ["src/**/*.ts", "src/**/*.tsx"],
+      "severity": "warn"
+    },
+    {
+      "id": "code-style.no-any",
+      "title": "Use unknown + type guards, not any",
+      "pattern": ":\\s*any\\b|<any>|as\\s+any\\b",
+      "fileGlobs": ["src/**/*.ts", "src/**/*.tsx"],
+      "exclude": ["**/*.d.ts"],
+      "severity": "warn"
+    },
+    {
+      "id": "code-style.no-ts-ignore-without-comment",
+      "title": "@ts-ignore must include a reason",
+      "pattern": "@ts-ignore(?!\\s*[—:-])",
+      "fileGlobs": ["src/**/*.ts", "src/**/*.tsx"],
+      "severity": "warn"
+    }
+  ]
+}

package/catalog/rules/claude-rules/example.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+---
+
+# Example path-scoped rule (CUSTOMISE OR DELETE)
+
+> This file was shipped by `haac-aikit` as a starter. It demonstrates the 2026
+> `.claude/rules/` mechanism: rules with a `paths:` frontmatter load **only when
+> Claude reads a matching file**, saving context.
+>
+> Edit it to match your project's conventions, change the `paths:` glob, or
+> delete the file entirely. See `docs/claude-md-reference.md` §6 for the full
+> spec.
+
+## Conventions for files matching the `paths:` glob
+
+<!-- Rule IDs let `aikit doctor --rules` track each rule's fire-rate and
+     violation-rate over time. Match the ID exactly in `aikit-rules.json` if
+     you want pattern-based violation detection on top of the load-time log. -->
+
+- <!-- id: code-style.no-default-export --> Use named exports, not `export default`.
+- <!-- id: code-style.no-any --> Use `unknown` + type guards instead of `any`.
+- <!-- id: code-style.no-console-log --> No `console.log` in production code (remove before commit).
+- Prefix the most load-bearing rules with `IMPORTANT:` or `YOU MUST` —
+  Anthropic guidance says emphasis improves adherence.
+
+## How to add another rule
+
+Create another `.md` file in `.claude/rules/`. Without `paths:` frontmatter, the
+rule loads on every session. With `paths:`, it loads only when Claude reads a
+matching file. Subdirectories like `.claude/rules/frontend/` are supported.
+
+## How to delete this file
+
+`rm .claude/rules/example.md`. `aikit diff` will then report it as missing on
+the next run; ignore the warning or run `aikit sync --force` to suppress it.

package/catalog/skills/tier1/software-architect.md

@@ -0,0 +1,42 @@
+---
+name: software-architect
+description: Use when a task introduces new services, cross-module data flow, external integrations, schema changes, or API design — pauses implementation to produce an RFC before planning begins. Also invokable explicitly.
+version: "1.0.0"
+source: haac-aikit
+license: MIT
+---
+
+## When to use
+
+Auto-trigger when ANY of:
+- New service, module, or package being introduced
+- Cross-module data flow or shared state
+- New external integration (API, DB, queue, auth provider)
+- Schema or data model changes
+- API surface being designed (REST, GraphQL, events)
+- Feature touches ≥ 3 files across different domains
+
+Explicit trigger: user says "run the architect", "design this first", "RFC for X"
+
+## Process
+
+1. **Pause** — do not write code or a plan yet.
+
+2. **Explore** — read the codebase for existing patterns relevant to the decision; identify files, modules, and conventions already in use. Never design around patterns you haven't verified exist.
+
+3. **Identify decisions** — surface the 2-3 key architectural choices this feature requires. Name each one explicitly.
+
+4. **Dispatch the `architect` agent** with:
+   - Feature description and goals
+   - Relevant existing files and patterns found in exploration
+   - Known constraints (performance, security, backwards compat, deadline)
+
+5. **Wait** — do not invoke `writing-plans` until the RFC artifact exists at `docs/decisions/YYYY-MM-DD-<topic>.md` and is committed.
+
+## Anti-patterns to avoid
+
+- Skipping to implementation when trigger conditions are met
+- Producing a plan before an RFC exists
+- Making design decisions inline in conversation without a committed artifact
+- Inventing patterns that already exist in the codebase
+- Running the architect agent without first exploring existing code (the agent needs grounded context)