create-ccc-tutor 0.1.0

package/template/.harness/skills/add-anti-flag/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: add-anti-flag
+description: Append an anti-flag rule to AGENTS.md so the auditor stops flagging a project-specific convention as a false positive. Use when an audit produced a finding that's actually a deliberate project decision (not a bug). Trigger when the user invokes /add-anti-flag, says "this is a false positive don't flag", "add an anti-flag rule", "auditor is wrong about X", or similar suppress-the-finding intent.
+allowed-tools: Read, Edit, Bash(date:*), Bash(grep:*)
+argument-hint: <text describing the convention being flagged incorrectly>
+---
+
+# /add-anti-flag
+
+Grow the L2 anti-flag rules in `AGENTS.md` over time. Each new rule tells the auditor (MAGI / `{{auditor_model}}`) that a specific project-specific convention LOOKS like an issue but is deliberately how this project does it — don't flag it as a finding.
+
+> *Companion to `/add-constitution-clause`. Anti-flag rules are area-level conventions; red lines are project-wide identity. Most "this is fine, stop flagging it" content belongs here, not in the constitution.*
+
+## Language Awareness
+
+This skill's instructions are in English. When you talk to the user (asking the criteria questions, proposing the rule, confirming), use the user's OS locale language. See `CLAUDE.md § Language Awareness`. The text written INTO `AGENTS.md` stays verbatim per what the user approves; do not translate user-entered convention content.
+
+## What this skill produces
+
+A modified `AGENTS.md` with one new anti-flag bullet appended to the `## Anti-flag rules — do NOT flag these as issues` section. The `### Architecture posture (default, applies to all projects)` sub-section stays untouched.
+
+---
+
+## Step 0 — Pre-flight
+
+1. Verify `AGENTS.md` exists at project root. If missing, fail with:
+
+   ```
+   AGENTS.md not found — run /init first.
+   ```
+
+   Halt the skill.
+
+2. Read `AGENTS.md` fully (Read tool).
+
+3. Locate the anti-flag rules section. Look for either:
+
+   - The `{{anti_flag_rules}}` placeholder (early project, no anti-flag rules yet), OR
+   - Already-rendered bullet rules under `## Anti-flag rules — do NOT flag these as issues` and before `### Architecture posture (default, applies to all projects)`.
+
+   If neither is present, surface the issue and halt — the AGENTS.md structure has been edited beyond what this skill can safely modify.
+
+---
+
+## Step 1 — Understand the convention
+
+1. Parse `$ARGUMENTS` as the convention description.
+
+2. If `$ARGUMENTS` is empty, ask:
+
+   ```
+   What convention is the auditor incorrectly flagging? Describe:
+     - What X is (the correct pattern in THIS project)
+     - What Y is (the alternative the auditor keeps suggesting)
+     - Why X is right for this project
+   ```
+
+   **Wait for user response before continuing.**
+
+---
+
+## Step 2 — Validate this is actually project-specific
+
+Anti-flag rules are for **project-specific conventions** that look universally wrong but are actually right for this project. Walk the user through the 3 criteria:
+
+```
+Before adding, confirm:
+
+  1. Is this convention SPECIFIC to this project, not a universal best
+     practice that just happens to be ignored here?
+     (If it's a universal best practice, the auditor is right; fix the code,
+     don't suppress the warning.)
+     Example fail: "Don't flag missing try/catch" (universal best practice — fix the code)
+     Example pass: "Don't suggest TypeScript — this project deliberately stays
+                   plain JS for zero-build static deploy"
+
+  2. Is the auditor's suggestion (Y) actually WRONG for this project,
+     not just suboptimal?
+     (If Y is also OK, just slightly preferred elsewhere, don't add a rule —
+     the auditor's advisory is fine to ignore case-by-case.)
+     Example fail: "Don't suggest extracting helper functions" (Y is fine,
+                   just not always needed — case-by-case judgment is OK)
+     Example pass: "Don't suggest CDN libs — every JS file must be in this
+                   repo, no external deps allowed"
+
+  3. Does this rule have a documented reason that future-you will agree
+     with in 6 months?
+     (Reason should be a constraint or trade-off, not a passing whim.)
+
+Does your proposed anti-flag rule meet all three criteria?
+  [y] yes — proceed
+  [n] no — reconsider; cancel
+  [explain] help me judge
+
+Wait for user response before continuing.
+```
+
+Branch:
+
+- `[y]` → proceed to Step 3.
+- `[n]` → abort silently; write nothing.
+- `[explain]` → ask which criterion the user is unsure about, walk through it with them, then re-present y/n. Loop until `[y]` or `[n]`.
+
+---
+
+## Step 3 — Format the rule
+
+Use the default anti-flag rule format per AGENTS.md's template:
+
+```markdown
+- **<X> is correct, <Y> is BANNED.**
+  Don't suggest switching to Y. (Reason: <why this project chose X>)
+```
+
+Propose the formatted rule to the user with their content filled in:
+
+```
+Proposed anti-flag rule to append to AGENTS.md:
+
+  - **<convention X> is correct, <alternative Y> is BANNED.**
+    Don't suggest switching to Y. (Reason: <reason>)
+
+Approve?
+  [a] approve as proposed
+  [b] modify (tell me what to change)
+  [c] cancel
+
+Wait for user response before continuing.
+```
+
+Branch:
+
+- `[a]` → proceed to Step 4.
+- `[b]` → accept user revisions to X, Y, or Reason; re-show the proposal; loop until `[a]` or `[c]`.
+- `[c]` → abort silently; write nothing.
+
+---
+
+## Step 4 — Apply edit
+
+Use the Edit tool to append the new rule to the anti-flag section in `AGENTS.md`.
+
+Placement rules:
+
+- If the `{{anti_flag_rules}}` placeholder is still present in the section → **replace** the placeholder with the new rule (becomes the first rule).
+- If `{{anti_flag_rules}}` has already been replaced with rendered content (one or more bulleted rules) → **append** the new rule after the last existing rule, maintaining the bulleted list format. Place the new rule consistently AFTER existing user-added rules.
+
+Do NOT touch:
+
+- The `### Architecture posture (default, applies to all projects)` sub-section — that's the stack-agnostic default, shipped with the harness and not user-grown.
+- Any other part of `AGENTS.md` (the auditor identity preamble, `## Your role`, `## Doc-in-sync verification`, `## Verdict output`, etc.).
+
+This skill writes to the anti-flag bullet list ONLY.
+
+---
+
+## Step 5 — Wrap up
+
+Display to the user (in their locale):
+
+```
+✓ Anti-flag rule appended to AGENTS.md.
+
+The auditor (MAGI / {{auditor_model}}) will skip this finding in future audits.
+
+  - <X> is correct, <Y> is BANNED.
+
+If a future audit still flags this, two reasons:
+  1. The rule wording doesn't catch the pattern — refine via re-running /add-anti-flag with clearer X/Y/Reason
+  2. The flagged code doesn't match the rule's convention — the finding may be valid
+
+Commit when ready (use /commit).
+```
+
+---
+
+## Rules
+
+- **Never bypass the 3-criteria validation** (Step 2). Universal best practices and case-by-case advisories don't belong in anti-flag rules.
+- **Never edit the Architecture posture sub-section.** It is stack-agnostic default content shipped with the harness; user-added rules go in the upper anti-flag list.
+- **Never commit or push from this skill.** Edits land as working-tree changes. The user commits via `/commit` when ready.
+- **Never touch other parts of `AGENTS.md`** beyond the anti-flag bullet list. Identity preamble, role, verdict schema, etc. are out of scope.
+- **Never translate user-entered convention content.** Write verbatim what the user approved at Step 3.
+
+---
+
+## Trust contract
+
+- This skill modifies **exactly one file**: `AGENTS.md`.
+- It writes to the anti-flag bullet list section only; Architecture posture and all other sections stay untouched.
+- If the user cancels at any confirmation step, nothing is written.
+- The skill makes no assumptions about which audits produced the finding — it captures the convention the user describes, no investigation of past audits.
+
+---
+
+## Completion criteria
+
+`/add-anti-flag` is complete when:
+
+- Step 0 has run (pre-flight checks pass; anti-flag section located)
+- Step 1 has captured the convention description
+- Step 2 has been answered `[y]` (or cancelled — in which case nothing else runs)
+- Step 3 has been approved by the user (or cancelled)
+- Step 4 has appended the new rule to the anti-flag bullet list
+- Step 5 has displayed the wrap-up message

package/template/.harness/skills/add-constitution-clause/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: add-constitution-clause
+description: Append a new project-specific red line to constitution.md § Section 3. Use when the user wants to add a project-wide, absolute, identity-changing rule. The skill validates the rule meets the 3 promotion criteria (project-wide / absolute / identity-changing) and refuses to add area-specific or contextual rules. Trigger when the user invokes /add-constitution-clause, says "add a red line", "add a project rule", "promote this to constitution", or similar identity-rule intent.
+allowed-tools: Read, Edit, Bash(date:*), Bash(grep:*)
+argument-hint: <text of the new red line>
+---
+
+# /add-constitution-clause
+
+Append a new project-specific red line to `constitution.md § Section 3 — Project-specific red lines`. Smaller surface than `/constitution-edit` (which also handles Section 2 and the slot registry); this skill only writes to Section 3.
+
+> *Spec-Kit-pattern audit trail. The Sync Impact Report turns ad-hoc constitution edits into versioned, semver-bumped, auditable changes.*
+
+## Language Awareness
+
+This skill's instructions are in English. When you talk to the user (asking the criteria questions, proposing the clause, confirming), use the user's OS locale language. See `CLAUDE.md § Language Awareness`. The text written INTO `constitution.md` stays verbatim per what the user approves; do not translate user-entered content.
+
+## What this skill produces
+
+A modified `constitution.md` with:
+
+1. A new numbered clause appended to Section 3 (Project-specific red lines).
+2. A Sync Impact Report HTML comment regenerated at the top of the file documenting the new clause.
+
+---
+
+## Step 0 — Pre-flight
+
+1. Verify `constitution.md` exists at project root:
+
+   ```bash
+   test -f constitution.md
+   ```
+
+   If missing, fail with the message:
+
+   ```
+   constitution.md not found — run /init first.
+   ```
+
+   Halt the skill.
+
+2. Read `constitution.md` fully (Read tool).
+
+3. Extract the current version from any existing Sync Impact Report block at the top:
+
+   ```bash
+   grep -m1 -oE 'Version: [0-9]+\.[0-9]+\.[0-9]+ →' constitution.md
+   ```
+
+   If no Sync Impact Report block exists, treat the current state as `1.0.0`.
+
+---
+
+## Step 1 — Understand the rule
+
+1. Parse `$ARGUMENTS` as the proposed red line text.
+
+2. If `$ARGUMENTS` is empty, ask:
+
+   ```
+   What's the red line you want to add? Describe the constraint in one or two sentences.
+   ```
+
+   **Wait for user response before continuing.**
+
+---
+
+## Step 2 — Validate against the 3 promotion criteria
+
+The constitution.md § Section 3 prelude lists 3 promotion criteria. A rule should only be promoted to Section 3 if it meets ALL THREE:
+
+- Project-wide scope (NOT area-specific)
+- Absolute (no exceptions, no lane override)
+- Identity-changing (violating it makes this no longer this project)
+
+Walk the user through these checks. Display:
+
+```
+Before adding to Section 3, confirm this rule meets all THREE criteria:
+
+  1. PROJECT-WIDE SCOPE — does this rule apply across the whole project?
+     (Area-specific rules belong in rule sources or scoped CLAUDE.md, not here.)
+     Example fail: "All React components must use TypeScript" (area-specific to frontend)
+     Example pass: "PII must never be sent to client without RLS gating" (project-wide)
+
+  2. ABSOLUTE — does this rule admit ZERO exceptions?
+     (Rules with lane overrides or "unless X" carve-outs belong in operating
+     principles, not red lines.)
+     Example fail: "Tests required, except trivial-lane" (has lane exception)
+     Example pass: "No third-party trackers in production" (absolute)
+
+  3. IDENTITY-CHANGING — would violating this rule mean this is no longer
+     THIS project?
+     (Rules that are merely "preferences" or "best practices" don't qualify.)
+     Example fail: "Use 2-space indent" (style preference, not identity)
+     Example pass: "No user data leaves the EU" (identity for an EU-only product)
+
+Does your proposed rule meet ALL three criteria?
+  [y] yes — proceed
+  [n] no — let me reconsider; cancel this skill
+  [explain] tell me which criterion(ia) you're unsure about, I'll help judge
+
+Wait for user response before continuing.
+```
+
+Branch:
+
+- `[y]` → proceed to Step 3.
+- `[n]` → abort silently; write nothing.
+- `[explain]` → ask which criterion the user is unsure about, walk through it with them in plain language, then re-present the y/n choice. Loop until `[y]` or `[n]`.
+
+---
+
+## Step 3 — Format the clause
+
+Format the user's text as a numbered Section 3 clause. Convention:
+
+```markdown
+### N. <short title in title case>
+
+<one-paragraph rule statement>
+```
+
+Where `N` is the next available number in Section 3. Read `constitution.md` to find the highest existing clause number under `## Section 3 — Project-specific red lines` (look for `### N.` headings); increment by 1. If Section 3 has no existing clauses yet (still holds the `{{project_red_lines}}` placeholder or is empty after the prelude), use `N = 1`.
+
+Propose a short title in title case derived from the rule text (Tech Lead chooses a reasonable phrase). Show the formatted version to the user:
+
+```
+Proposed clause to append to Section 3:
+
+  ### <N>. <title>
+
+  <text>
+
+Approve?
+  [a] approve as proposed
+  [b] modify (tell me what to change)
+  [c] cancel
+
+Wait for user response before continuing.
+```
+
+Branch:
+
+- `[a]` → proceed to Step 4.
+- `[b]` → accept user revisions to title and/or body; re-show the proposal; loop until `[a]` or `[c]`.
+- `[c]` → abort silently; write nothing.
+
+---
+
+## Step 4 — Apply edit
+
+Use the Edit tool to append the new clause to `## Section 3 — Project-specific red lines` in `constitution.md`.
+
+Placement rules:
+
+- If the `{{project_red_lines}}` placeholder is still present in Section 3 (early project, Section 3 has no clauses yet), **replace** the placeholder with the new clause.
+- If `{{project_red_lines}}` has already been replaced with rendered content (one or more `### N.` clauses), **append** the new clause AFTER the last existing clause.
+
+Do NOT touch:
+
+- The Section 3 prelude (the `> Starts empty…` blockquote and the 3-criteria bullet list).
+- Section 1 (Universal Core) — harness-guaranteed, read-only.
+- Section 2 (Project Identity) — out of scope for this skill (use `/constitution-edit` for Section 2 changes).
+- The slot registry HTML comment.
+
+---
+
+## Step 5 — Generate Sync Impact Report
+
+Identical machinery to `/constitution-edit`. Compute bump = MINOR (this skill always adds new content). Compute new version from old (`X.Y.Z` → `X.(Y+1).0`).
+
+Build the report block. Use `date -u +%Y-%m-%dT%H:%M:%SZ` for the timestamp:
+
+```html
+<!-- Sync Impact Report
+Version: <old> → <new> (MINOR — add Section 3 clause #N: <title>)
+Modified items:
+  - Section 3 — added clause #N: <title>
+Templates needing update:
+  - <any files referencing {{project_red_lines}}>
+Generated: <ISO 8601 UTC>
+-->
+```
+
+If no other files reference `{{project_red_lines}}`, write `Templates needing update:` followed by `  - N/A`.
+
+Placement:
+
+- If an existing Sync Impact Report block already lives at the top of `constitution.md` (immediately after the title heading), **REPLACE** it with the new block. Only one block lives in the file at a time — `git log` is the audit trail.
+- Otherwise, **INSERT** the new block immediately after the title line (`# <project> — Constitution`) and before the next content.
+
+---
+
+## Step 6 — Wrap up
+
+Display to the user (in their locale):
+
+```
+✓ Constitution updated to version <new>.
+
+New clause #N appended to Section 3:
+  "<title>"
+
+Sync Impact Report regenerated at top of constitution.md.
+
+Next steps:
+  1. Commit when ready (use /commit).
+  2. If this clause has implications for existing code, audit with /audit-spec.
+```
+
+---
+
+## Rules
+
+- **Never edit Section 1 or Section 2.** Use `/constitution-edit` for Section 2 changes; Section 1 is harness-guaranteed and cannot be edited by any skill.
+- **Never skip the 3-criteria validation in Step 2.** A rule that fails any one of project-wide / absolute / identity-changing belongs elsewhere (operating principles, rule sources, anti-flag rules), not in Section 3.
+- **Never commit or push from this skill.** Edits land as working-tree changes. The user commits via `/commit` when ready.
+- **Always regenerate the Sync Impact Report** (consistency with `/constitution-edit` — Section 3 edits are versioned changes).
+- **Never translate user-entered clause content.** Write verbatim what the user approved at Step 3.
+
+---
+
+## Trust contract
+
+- This skill modifies **exactly one file**: `constitution.md`.
+- It only writes to Section 3 and the Sync Impact Report block; Sections 1, 2, the slot registry, and the prelude of Section 3 stay untouched.
+- If the user cancels at any confirmation step, nothing is written.
+- The Sync Impact Report is always regenerated fresh — only one block at a time in the file.
+
+---
+
+## Completion criteria
+
+`/add-constitution-clause` is complete when:
+
+- Step 0 has run (pre-flight checks pass)
+- Step 1 has captured the proposed rule text
+- Step 2 has been answered `[y]` (or cancelled — in which case nothing else runs)
+- Step 3 has been approved by the user (or cancelled)
+- Step 4 has appended the new clause to Section 3
+- Step 5 has regenerated the Sync Impact Report at the top of `constitution.md`
+- Step 6 has displayed the wrap-up message