@novare-technologies/nvaid 0.0.0-stage → 0.1.0

package/templates/rules/customer-experience-contract-generation-rules.md

@@ -0,0 +1,51 @@
+---
+document: Customer Experience Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "[Customer Experience Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Customer Experience Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Customer Experience
+Contract for an Intent, during Mob Elaboration Phases 2–5 — what triggers producing one,
+and what it must contain when it does.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/customer-experience-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Customer Experience
+Architect accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+**Always.** Every Intent originates from, or must be validated against, a real business
+need — the Customer Experience Architect is the one who closes that loop after the
+technical contracts land, confirming the room's final shape still serves it.
+
+## 2. Required Content
+
+- **Reconciliation Against the Original Intent.** Where the final, technically-grounded
+  shape narrowed, resolved, or held unchanged against what `intent.md` originally said —
+  named explicitly, not silently absorbed into the acceptance criteria without comment.
+- **Final Acceptance Criteria.** The technically-grounded version of the Intent's own
+  Success Criteria, incorporating what the other contracts actually committed to — not a
+  restatement of the Intent verbatim.
+- **What "Done" Looks Like to the Business.** Tied to a concrete validation scenario, not
+  "the code merged."
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |

package/templates/rules/frontend-architecture-contract-generation-rules.md

@@ -0,0 +1,56 @@
+---
+document: Frontend Architecture Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "[Identity Access and Frontend Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Frontend Architecture Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Frontend (Identity
+Access and Frontend) Architecture Contract for an Intent, during Mob Elaboration Phases
+2–5 — what triggers producing one, and what it must contain when it does.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/frontend-architecture-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Identity Access and
+Frontend Architect accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+Any Intent with at least one Unit touching the frontend (web or mobile), a design
+system component, or an identity/access/RBAC/SSO surface. Skipped only for Intents with
+zero user-facing or access-model impact — rare, since most Intents eventually surface
+somewhere in the UI.
+
+## 2. Required Content
+
+- **Consumes.** Which Backend contract (if any) this one consumes verbatim, with
+  confirmation that no field is locally reinterpreted or renamed.
+- **UI Flow.** The concrete step-by-step, tied to specific screens or components — not a
+  general description of the feature.
+- **Shared Derivations, Sourced Not Re-Derived.** Point to the Backend contract's version
+  of anything both roles need (an ID derivation, a naming rule); never re-derive it
+  independently.
+- **Identity / Access Implications.** Stated explicitly even when the answer is "none for
+  this Intent" — never left implicit. This is the one open risk area (SRS §9, no
+  RBAC/SSO in POC scope) most likely to get silently assumed away if it isn't required in
+  writing every time.
+- **Components Touched (Design-Code Dictionary impact).**
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |

package/templates/rules/quality-architecture-contract-generation-rules.md

@@ -0,0 +1,86 @@
+---
+document: Quality Architecture Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.5.0
+owner: "[Quality Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Quality Architecture Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Quality Architecture
+Contract for an Intent, during Mob Elaboration Phases 2–5 — what triggers producing one,
+and what it must contain when it does. This file owns the **Intent-Specific Gates** only
+(`PROJECT-RULES.md` §5.2) — content that's regenerated fresh per Intent. It does not
+define, and a generated contract must never redefine, the **Solution-Specific Gates**
+(Build, Code Coverage, Code Quality, Reusability/Duplication, Regression Test, SAST) —
+those are fixed codebase-wide thresholds set once in §5.2, not something any single
+Intent opts into or out of.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/quality-architecture-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Quality Architect
+accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+**Almost always.** Any Intent that reaches Implementation (Fig. 2 Stage 6) at all gets a
+Quality Architecture Contract. The rare exception is an Intent whose Units are pure
+documentation or process changes with no code path to test.
+
+## 2. Required Content
+
+- **Required Test Coverage table.** One row per meaningful scenario, and — this is the
+  load-bearing rule, not a formatting preference — **every row traces to one of the
+  owning Unit's own stated Acceptance Criteria** (`unit-XXX-design.md`, per
+  `unit-breakdown-rules.md` §2), not surfaced independently from Elaboration discussion
+  and hoped to line up. Each row is also classified by type — never left as an unlabeled
+  list:
+  - **Happy Path** — the primary success scenario(s).
+  - **Negative Path** — deliberate invalid input, with a specific expected failure
+    response (not just "it errors").
+  - **Edge Case** — a boundary condition or ambiguous scenario that's neither a clean
+    success nor a clean rejection. This is where a Known Gap most often originates — see
+    below.
+
+  **Both directions of the trace are checked, not just one:** every Acceptance
+  Criterion gets at least one covering row, and every row names the criterion it
+  verifies — or is marked explicitly supplementary rather than left looking like
+  undocumented coverage. A criterion with no covering row is a Known Gap, logged below,
+  not silently assumed to be "probably fine." The worked example demonstrates exactly
+  this: one row in `quality-architecture-contract.md` traces to nothing, which is how
+  its Known Gap got caught rather than missed.
+
+  Collectively, this table is what `PROJECT-RULES.md` §5.2's Unit Test Gate (and, where
+  more than one component is touched, the Integration Test Gate) run against — both
+  Intent-Specific. See §5.2 for the full nine-gate taxonomy and where the line sits
+  against the six fixed Solution-Specific gates this file never touches.
+- **NFRs in Scope (Intent NFR gate).** Which of the SRS's existing non-functional
+  requirements this Intent's Units are held to, *beyond* the solution-wide baseline
+  §5.2 already sets; state "none beyond the standing baseline" explicitly when true,
+  rather than leaving the section blank.
+- **Known Gaps.** Anything the room identified as untested and consciously accepted —
+  flagged, not silently dropped. Matches the worked example's `{user}`-derivation
+  collision gap.
+- **Definition of Done addition**, specific to this Intent, beyond `PROJECT-RULES.md`
+  §5.1's standing checklist — only if this Intent actually needs one.
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |
+| 0.2.0 | [date] | Required Test Coverage rows must now be classified Happy Path / Negative Path / Edge Case, and explicitly tied to `PROJECT-RULES.md` §5.2's Unit/Integration Test Gates | Quality gate types were unspecified; §5.2 was a placeholder |
+| 0.3.0 | [date] | Scoped this file to Intent-Specific Gates only; Solution-Specific Gates (Code Coverage, Code Quality, Reusability, SAST, Build) are fixed in §5.2 and out of scope for any generated contract | Gate taxonomy split into Intent-Specific vs. Solution-Specific categories |
+| 0.4.0 | [date] | Required Test Coverage rows must now trace to the owning Unit's stated Acceptance Criteria in both directions — every criterion covered, every row justified | Should a Unit's acceptance criteria be the same thing its unit tests are based on? |
+| 0.5.0 | [date] | Solution-Specific gate list now includes Regression Test (added in `PROJECT-RULES.md` §5.2) — six fixed gates, nine total | Should Quality Gates include a card for regression testing? |

package/templates/rules/solutions-architecture-contract-generation-rules.md

@@ -0,0 +1,59 @@
+---
+document: Solutions Architecture Contract — Generation Rules
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "[Solutions Architect name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Solutions Architecture Contract: Generation Rules
+
+**What this file is:** the rules the AI agent follows to draft a Solutions Architecture
+Contract for an Intent, during Mob Elaboration Phases 2–5 — what triggers producing one,
+and what it must contain when it does.
+
+**What this file is not:** not the worked example —
+`docs/templates/samples/contracts/solutions-architecture-contract.md` is the canonical
+shape and sign-off format, filled in for `INTENT-004`. Not the draft/human-edit
+relationship either — every generated contract is a starting framework, never a verdict;
+see the AI-Native Engineering Model's §Mob Elaboration for how the Solutions Architect
+accepts, extends, or simplifies it before Sign-Off.
+
+**Companion files:** [unit-breakdown-rules.md](./unit-breakdown-rules.md) (same
+Elaboration session). The other five `*-architecture-contract-generation-rules.md` files
+are siblings, one per role.
+
+---
+
+## 1. When This Contract Is Required
+
+**Always.** Every Intent gets a Solutions Architecture Contract, even when the honest
+assessment is "no cross-cutting impact, no new ADR needed." This is the one contract
+never marked "not pulled in" — someone has to always confirm nothing systemic was
+missed, and that confirmation *is* the contract. An empty-looking assessment is a
+completed one, not a skipped one.
+
+## 2. Required Content
+
+- **System-Level Assessment.** Does this Intent introduce a new system container, cross
+  a boundary named in the SRS's System Containers (Fig. 2), or need a new ADR? State the
+  answer plainly, including when it's "no" on every count — don't omit the section
+  because the answer is negative.
+- **What This Intent Is Allowed to Touch.** An explicit boundary statement: which
+  containers/components are in scope for this Intent's Units of Work, and which are
+  explicitly out.
+- **AI-Agent Guardrail Implications.** Does this Intent introduce any unsupervised-action
+  surface `PROJECT-RULES.md` §7 doesn't already cover — a new destructive operation, a
+  new external API call, a new credential path? Flag it explicitly; don't assume the
+  existing rules cover a case they were never written against.
+- **Cross-Role Consistency Check.** Confirms the other contracts produced this session
+  don't contradict each other — this is the Solutions Architect's half of Phase 6's
+  Consistency Gate, recorded in writing rather than only spoken in the room.
+- **Sign-Off.**
+
+## 3. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Companion to the five sibling `*-contract-generation-rules.md` files |

package/templates/rules/unit-breakdown-rules.md

@@ -0,0 +1,121 @@
+---
+document: Unit of Work Decomposition Rules
+project: "{{PROJECT_NAME}}"
+version: 0.2.0
+owner: "[Process Facilitator name]"
+last_updated: "[YYYY-MM-DD]"
+status: draft
+---
+
+# Unit of Work Decomposition Rules
+
+**What this file is:** the rules the AI agent follows when proposing a Unit of Work
+breakdown at Mob Elaboration Phase 2 (Strawman Review) — how to cut one Intent into
+Units, how to classify each Unit as a Story or a Bug, and the sizing signals that say a
+strawman is cut wrong before the room spends time negotiating around a bad boundary.
+
+**What this file is not:** not the ticket field shape (`ISSUE-TRACKER-TEMPLATE.md`
+governs that), not the ceremony's choreography (the AI-Native Engineering Model's
+§ Mob Elaboration governs that), not the Intent template itself. This file governs
+one specific judgment call: given an approved Intent, what its Units of Work are.
+
+**Companion files:** [ISSUE-TRACKER-TEMPLATE.md](./ISSUE-TRACKER-TEMPLATE.md) is where a
+Unit of Work, once decided here, becomes a ticket. [PROJECT-RULES.md](./PROJECT-RULES.md)
+§7 rule 12 is the operating rule this file implements.
+
+---
+
+## 1. What a Unit of Work Is
+
+The smallest slice of an Intent that can be:
+
+- **designed** by one owning role, without needing another role's design to already
+  exist first (though it may *reference* another role's contract),
+- **gated** independently at Fig. 2's Stage 5 (Per-Unit Design Approved) and Stage 8
+  (Merge Approval), without waiting on a sibling Unit's gate, and
+- **implemented** by the AI agent in one sitting, without losing the earlier reasoning
+  in its own context (`PROJECT-RULES.md` §7 rule 8, scope discipline).
+
+A Unit of Work is never split further inside the ticket tracker by default
+(`ISSUE-TRACKER-TEMPLATE.md` §2) — the Unit boundary *is* the atomic boundary. If a
+"Unit" doesn't fit in one sitting, it was cut wrong; fix the cut, don't add sub-tasks
+around it.
+
+## 2. Acceptance Criteria — every Unit states its own
+
+A Unit of Work carries its own Acceptance Criteria, stated once in its design doc
+(`unit-XXX-design.md`, Fig. 2 Stage 4) — narrowed from the Intent's own Success Criteria
+(`intent.md`) down to just this Unit's slice. Not a restatement of the whole Intent's
+criteria on every Unit; each Unit states only the part of "done" that's actually its own
+to satisfy.
+
+**The traceability rule this exists to enforce:** the Quality Architecture Contract's
+Required Test Coverage table (`quality-architecture-contract-generation-rules.md` §2) is
+generated *from* this list, not surfaced independently and hoped to line up. Every
+stated Acceptance Criterion gets at least one Happy Path, Negative Path, or Edge Case
+test row that verifies it; every test row traces back to a criterion it verifies, or is
+marked explicitly supplementary rather than left looking like undocumented coverage. A
+criterion with no covering test row is a Known Gap (`PROJECT-RULES.md` §6) the same way
+an untested edge case already is — not silently assumed to be "probably fine."
+
+Without a named source, a Unit's tests and its actual "done" bar are two independently
+populated lists that happen to usually agree — right up until they don't. This is the
+rule that closes that gap. See the worked example: `unit-004-02-backend-design.md`'s
+four Acceptance Criteria are what `quality-architecture-contract.md`'s test table
+traces to, row by row — including the one row that traces to nothing, which is exactly
+how that Unit's Known Gap got caught instead of missed.
+
+## 3. Story or Bug — the classification rule
+
+Every Unit of Work is exactly one of these two ticket types. Classify per Unit, not per
+Intent — one Intent can produce a mix of both.
+
+| Classify as | When | Example |
+|---|---|---|
+| **Story** | The Unit adds or changes a capability — net-new or intentionally different behavior | The branch-override selector itself (`UNIT-004-01`) |
+| **Bug** | The Unit brings existing, already-shipped behavior back in line with a spec, contract, or FR it currently violates | A previously merged Unit's `{user}` derivation collides on two usernames in production |
+
+**Boundary case:** a defect found *during* Construction of a Story, before that Story's
+own Merge Approval, is fixed inside that same Unit — it does not spin out as a separate
+Bug. Only a defect discovered *after* a Unit has already merged becomes its own Bug-type
+Unit — under a fast, often single-Unit Intent of its own, or folded into a Known Gap per
+`PROJECT-RULES.md` §6 if it isn't urgent enough to justify a full Mob Elaboration pass by
+itself.
+
+## 4. Decomposition Heuristics
+
+Applied by the AI agent when proposing the Phase 2 strawman, and by the room when
+critiquing it:
+
+- **One primary owning role per Unit.** If a Unit's design would need two Architects to
+  co-author it, it's two Units connected by a contract, not one Unit that spans both.
+  This is what turns Fig. 2 Stage 4 into "×N roles in parallel" instead of one
+  tangled design.
+- **A shared dependency is a contract, not a split.** When two Units both need the same
+  answer to something (the worked example's `{user}` derivation rule), that answer is
+  negotiated once, in a contract, and referenced by both — never independently
+  re-derived, and never used as a reason to merge the two Units into one.
+- **Size to one sitting.** If a Unit's own design doc is trending toward the size of
+  several of the worked examples combined, that's a smell the Unit is actually two.
+- **Don't split to satisfy an org chart.** A Unit boundary is justified by an
+  independent design-and-gate need, never by "everyone should have something to own."
+  Splitting a naturally single-role, single-behavior change into two Units just to give
+  a second role a ticket produces busywork, not independence.
+- **Watch the Unit count as a signal, not a rule.** One Unit for an Intent that went
+  through full Joint Elaboration is a sign the Intent probably didn't need the
+  cross-role machinery at all. More than roughly six to eight Units is a sign the
+  "Intent" was actually several Intents bundled together and should have been split
+  before Elaboration, not after.
+
+## 5. Numbering
+
+`UNIT-<INTENT-NUMBER>-<sequence>`, zero-padded two digits — `UNIT-004-01`,
+`UNIT-004-02`, matching the worked example in `docs/templates/samples/`. Sequence order
+follows the order Units are listed in `unit-breakdown.md`, not build or gate order.
+
+## 6. Change Log
+
+| Version | Date | Change | Trigger |
+|---|---|---|---|
+| 0.1.0 | [date] | Initial version | Clarifying how Units of Work get decomposed, classified (Story/Bug), and sized, separate from how they're ticketed |
+| 0.2.0 | [date] | Added §2: every Unit states its own Acceptance Criteria, and the Quality Architecture Contract's test coverage table must trace to them, not be surfaced independently | Should a Unit's acceptance criteria be the same thing its unit tests are based on? |

package/templates/skills/backend/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: backend
+description: Drafts the Backend Architecture Contract for an Intent, per backend-architecture-contract-generation-rules.md. Use when asked to run the Backend Skill or draft a Backend contract during Mob Elaboration.
+invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
+output: file — nvaid/intents/<INTENT-ID>/contracts/backend-architecture-contract.md
+---
+
+# Backend Skill
+
+Drafts the Backend Architecture Contract for an Intent, per
+`{{AIDLC_ROOT}}/backend-architecture-contract-generation-rules.md` — the shapes every
+consuming role (most often Frontend) reproduces verbatim rather than re-deriving.
+
+## Steps
+
+1. Confirm this Intent has at least one Unit touching the backend — an API/service layer,
+   an async worker, a data schema, or any server-side component — if none do, this
+   contract is not produced; state that plainly rather than leaving the file absent
+   with no explanation.
+2. Write the full API Contract Exposed for any new or changed endpoint — request and
+   response shape, including error cases (4xx/5xx), not just the happy path.
+3. Define every Shared Derivation Rule (a naming rule, an ID derivation) exactly once
+   here; never let a consuming role re-derive it independently.
+4. State Data Model Touches — which tables/columns are written, and whether a migration
+   is needed.
+5. List components touched (Design-Code Dictionary impact).
+6. State what this contract deliberately excludes — anything the room discussed and
+   explicitly deferred, named rather than silently dropped.
+7. Write `nvaid/intents/<INTENT-ID>/contracts/backend-architecture-contract.md`.
+
+## Boundaries
+
+- A draft, not a verdict — flag it awaiting the Backend Solutions Architect's Sign-Off;
+  never present it as final.

package/templates/skills/customer-experience/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: customer-experience
+description: Drafts the Customer Experience Contract for an Intent, per customer-experience-contract-generation-rules.md. Use when asked to run the Customer Experience Skill or draft a Customer Experience contract during Mob Elaboration.
+invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
+output: file — intents/<INTENT-ID>/contracts/customer-experience-contract.md
+---
+
+# Customer Experience Skill
+
+Drafts the Customer Experience Contract for an Intent, per
+`docs/templates/customer-experience-contract-generation-rules.md` — reconciling what the
+room actually committed to against what `intent.md` originally asked for.
+
+## Steps
+
+1. Name explicitly where the final, technically-grounded shape narrowed, resolved, or
+   held unchanged against the original Intent — never silently absorbed.
+2. Write the Final Acceptance Criteria: the Intent's Success Criteria, incorporating
+   what the other contracts actually committed to, not a verbatim restatement.
+3. Tie "done" to a concrete validation scenario, never just "the code merged."
+4. Write `intents/<INTENT-ID>/contracts/customer-experience-contract.md`.
+
+## Boundaries
+
+- A draft, not a verdict — flag it awaiting the Customer Experience Architect's
+  Sign-Off; never present it as final.

package/templates/skills/daily-construction-update/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: daily-construction-update
+description: Generates the daily three-question Construction digest (Completed / In Progress / Impediments) and publishes it to Wiki.js. Use when asked to run the Daily Construction Update Skill or produce today's construction update.
+invoked_by: Mob Construction (Ceremony 2) — background, no meeting
+output: link — a Wiki.js page, updated in place
+---
+
+# Daily Construction Update Skill
+
+Replaces the Daily Standup with a generated report about Construction's ongoing work.
+The work itself keeps no fixed cadence — that doesn't change. What runs daily is the
+report, not the work.
+
+## Steps
+
+1. Query every in-flight Unit's ticket and gate status.
+2. Compose the three-question digest, translated from the standup's own questions:
+   **Completed** (Units Merged, Intents that became Shippable since the last update),
+   **In progress** (current WIP — Design, Building, Gates), **Impediments** (stalled
+   Units, repeated gate failures, anything flagged as a Known Gap).
+3. Publish to the team's Wiki.js page, updated in place — never a chat message that
+   scrolls out of reach.
+
+## Boundaries
+
+- Never block or gate a Unit's progress — only report state, the same way a daily sales
+  report doesn't stop the sales.

package/templates/skills/frontend/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: frontend
+description: Drafts the Frontend Architecture Contract for an Intent, per frontend-architecture-contract-generation-rules.md. Use when asked to run the Frontend Skill or draft a Frontend contract during Mob Elaboration.
+invoked_by: Mob Elaboration (Ceremony 1), Phases 2–5
+output: file — intents/<INTENT-ID>/contracts/frontend-architecture-contract.md
+---
+
+# Frontend Skill
+
+Drafts the Frontend Architecture Contract for an Intent, per
+`docs/templates/frontend-architecture-contract-generation-rules.md` — consuming the
+Backend contract's shapes verbatim rather than reinterpreting them.
+
+## Steps
+
+1. Name which Backend contract this one consumes, and confirm no field is locally
+   reinterpreted or renamed.
+2. Write the concrete UI flow, tied to specific screens or components, not a general
+   feature description.
+3. Point to the Backend contract's version of any shared derivation instead of
+   re-deriving it independently.
+4. State Identity/Access implications explicitly, even when "none for this Intent" —
+   never left implicit.
+5. List components touched (Design-Code Dictionary impact).
+6. Write `intents/<INTENT-ID>/contracts/frontend-architecture-contract.md`.
+
+## Boundaries
+
+- A draft, not a verdict — flag it awaiting the Frontend Architect's Sign-Off; never
+  present it as final.

package/templates/skills/github/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: github
+description: Branches (feature/bugfix/hotfix/intent/chore, mapped to ticket or Intent IDs, or a slug for repo tooling), commits, opens pull requests, checks CI, self-reviews before requesting human review, iterates on review comments, and hands off to manual merge approval, following this repo's master/develop Git Flow. Use when asked to run the GitHub Skill, start work on a ticket or an Intent, push a Unit's work, do repo tooling/config work, open or update a pull request, address review comments, or check CI status.
+invoked_by: Mob Construction (Ceremony 2), and Mob Elaboration (Ceremony 1) for its own intent/ branches
+output: link — a GitHub pull request
+version: 5.0
+---
+
+# GitHub Skill
+
+The procedure Mob Construction invokes to touch the repository — the same steps, every
+Unit, every time. Covers the full loop: branch → commit → PR → self-review → human
+review → iterate → manual merge. This Skill never merges anything itself.
+
+## Branch model (Git Flow)
+
+- **`master`** — the default, production branch. Nothing commits here directly; it only
+  moves forward via an approved release merge from `develop`, or a hotfix.
+- **`develop`** — the integration branch. Every feature and bugfix branch is cut from
+  here and merges back here.
+- **`feature/<story-id>`** — new capability, cut from `develop`. `<story-id>` is the
+  GitHub Project story ID this Unit's ticket carries — e.g. `feature/142`. Add a short
+  slug if the ID alone reads as opaque in a long branch list: `feature/142-branch-override`.
+- **`bugfix/<bug-id>`** — fixes a Bug-classified ticket found before release, cut from
+  `develop`, same ID convention as `feature/`.
+- **`hotfix/<slug>`** — an emergency fix to what's already in production, cut from
+  `master` directly (the one exception to "always branch from develop"), merged back
+  into **both** `master` and `develop` so the fix isn't lost on the next release. No
+  Unit exists yet when this starts — run the Unit Breakdown Skill retroactively to log
+  one once the fix is in.
+- **`intent/<intent-id>-<slug>`** — Mob Elaboration's own output, cut from `develop`:
+  `intent.md` itself, `unit-breakdown.md`, and the per-role `contracts/` files. Not a
+  Construction branch type — nothing here is code, so treating it as `feature/` would
+  misdescribe what actually changed and would demand a Story ID that doesn't exist yet
+  (a Unit of Work isn't decided until Elaboration produces `unit-breakdown.md` in the
+  first place). Review on this branch's PR is the CX Architect (or relevant Architect)
+  reading the artifact for content, not CI verifying code — the gates still run, but
+  pass on a markdown-only diff as a no-op, not as a meaningful check of anything.
+  Example: `intent/001-login-navigation-shell`.
+- **`chore/<slug>`** — repo tooling, config, or meta work with no application code and
+  no Unit of Work behind it: a new Skill, a CI/CD workflow change, a convention update
+  (this branch type's own addition was one). Cut from `develop`, same as `feature`/
+  `bugfix`. This was already the de facto convention across every tooling PR in this
+  repo before being written down here — `chore/ci-setup`, `chore/verify-bot-identity`,
+  `chore/manual-deploy-trigger`, `chore/pr-review-skill`, `chore/pr-title-convention`,
+  `chore/reconcile-spec-planning`, and others all predate this entry. This documents
+  existing practice, not a new rule nobody's followed yet.
+
+## Steps
+
+### 1. Branch
+
+Cut the branch per the model above, named by type and ticket ID (or Intent ID, for
+`intent/`) so what's happening is visible in the branch list itself. Never commit
+directly to `master` or `develop`.
+
+### 2. Commit
+
+One commit per meaningful step, not one giant diff, using Conventional Commits scoped
+to the Unit:
+
+```
+<type>(<unit-id>): <what changed, imperative mood>
+```
+
+`<type>` is `feat`, `fix`, `refactor`, `test`, or `chore`. Example:
+`feat(unit-004-02): add branch-override endpoint with slot-limit check`.
+
+On an `intent/` branch there's no Unit ID yet to scope to — use `docs: draft
+INTENT-XXX — <short title>` instead (no parenthesized scope). On a `chore/` branch
+there's no Unit ID either, since there's no Unit of Work behind tooling/config changes —
+use a plain `chore: <what changed, imperative mood>`, no parenthesized scope.
+
+### 3. Open the pull request
+
+Target `develop` (or `master` for a `hotfix/`). The PR body links the Unit's design doc
+and its Quality Architecture Contract, and lists which Acceptance Criteria this PR
+closes. Request the owning Architect (the human) as reviewer explicitly — never leave
+the reviewer field empty.
+
+**PR title format** — bracket tags, not a Conventional Commit prefix. Commits keep the
+`<type>(<unit-id>):` style from step 2; the PR *title* uses this readable form instead:
+
+```
+[TYPE][TARGET][TICKET] <plain readable summary>
+```
+
+- **`[TYPE]`** — the work type, mapped from the commit type:
+  `feat → [FEATURE]`, `fix → [FIX]`, `chore → [CHORE]`, `refactor → [REFACTOR]`,
+  `test → [TEST]`, `docs → [DOCS]`.
+- **`[TARGET]`** — the base branch this PR merges into:
+  `develop → [DEV]`, UAT branch → `[UAT]`, `master → [PROD]`.
+- **`[TICKET]`** — the ticket ID this Unit carries: the `UNIT-XXX-YY` Story/Bug
+  (e.g. `[UNIT-004-02]`), or the `INTENT-XXX` Epic when the PR spans the whole Intent.
+  These are the IDs from `{{AIDLC_ROOT}}/ISSUE-TRACKER-TEMPLATE.md`, mirrored into the GitHub
+  Project. **Omit this tag entirely** when the change has no ticket (e.g. repo tooling or
+  config) — never write an empty `[]`.
+- **`<summary>`** — a plain, human-readable sentence under ~70 chars. No `type:` prefix.
+
+Examples:
+- `[FEATURE][DEV][UNIT-004-01] Add branch-override selector to the environment form`
+- `[FIX][PROD][UNIT-004-02] Correct username derivation collision`
+- `[CHORE][DEV] Replicate Claude skills to Kiro` *(no ticket → no third tag)*
+
+### 4. Self-review before asking for human time
+
+Before flagging for human review, re-read the diff once against the Unit's own
+Acceptance Criteria and the Quality Architecture Contract's Required Test Coverage
+table. Catch what's catchable here — a missing negative-path test, an unhandled error
+case — so the human's review time goes to judgment calls, not things this Skill could
+have caught itself.
+
+### 5. Poll CI, self-correct on failure
+
+On a Guardrail Gate failure, self-correct and push again. Never ask for review while a
+gate is red.
+
+### 6. Iterate on review comments
+
+Once the human leaves review comments (`gh pr view <n> --comments` or the GitHub MCP
+server's structured comment tools, if configured):
+
+1. Read every open thread before changing anything — don't react comment-by-comment in
+   isolation when they interact.
+2. Address each with a targeted commit, not a rewrite of the whole diff.
+3. Reply to each thread stating what changed, then re-request review. Never mark a
+   thread resolved that this Skill left open-ended or partially addressed.
+
+### 7. Hand off to Merge Approval
+
+Once review is approved and every gate is green, flag the PR ready. Stop there. For a
+`hotfix/`, note explicitly in the PR that a second merge into `develop` is still needed
+after `master` receives this one — never assume the human will remember to ask for it.
+
+## Boundaries
+
+- Never merge the pull request, and never approve its own PR — Merge Approval is a
+  human gate this Skill can reach but not cross. (Repo branch protection enforces this
+  independently of this instruction.)
+- Never commit directly to `master` or `develop` — always through a typed branch, even
+  for a one-line fix.
+- Never resolve a review thread on the human's behalf.