@ax-skills/all 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,40 @@
1
+ Creative Commons Attribution 4.0 International (CC BY 4.0)
2
+
3
+ Copyright (c) 2026 Aaron Peloquin
4
+
5
+ Scope of This License:
6
+ This license applies to all written articles, documentation, architecture diagrams,
7
+ and agent skill definitions in this repository, specifically:
8
+
9
+ - content/articles/**
10
+ - .agents/skills/**
11
+
12
+ Exclusions:
13
+
14
+ - Application source code, configuration, and tooling (`src/**`, `eslint/**`,
15
+ and root config files) are licensed separately under the MIT License (`./LICENSE`).
16
+ - Custom brand marks (`public/logo.svg`, `public/favicon.svg`, `public/logo-badge.svg`)
17
+ are reserved brand assets (All Rights Reserved) and are not granted under CC BY 4.0.
18
+
19
+ You are free to:
20
+
21
+ - Share — copy and redistribute the material in any medium or format for any purpose,
22
+ even commercially.
23
+ - Adapt — remix, transform, and build upon the material for any purpose, even commercially.
24
+
25
+ Under the following terms:
26
+
27
+ - Attribution — You must give appropriate credit, provide a link to the license, and
28
+ indicate if changes were made. You may do so in any reasonable manner (including a
29
+ single-line slide-footer credit such as:
30
+ "Source: Aaron Peloquin, Agent Experience (AX) - agent-experience.ai (CC BY 4.0)"),
31
+ but not in any way that suggests the licensor endorses you or your use.
32
+ - No additional restrictions — You may not apply legal terms or technological measures
33
+ that legally restrict others from doing anything the license permits.
34
+
35
+ No Warranties:
36
+ This material is provided "as-is" without warranty of any kind, as set forth in Section 5
37
+ of the CC BY 4.0 Legal Code.
38
+
39
+ Full Legal Code:
40
+ <https://creativecommons.org/licenses/by/4.0/legalcode>
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aaron Peloquin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,48 @@
1
- # Temporary Holding Version
1
+ # `@ax-skills/all`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Complete Agent Experience (AX) skill suite combining Software Factory workflow skills, agent-ergonomic software engineering, and React architecture standards.
4
+
5
+ **Canonical Documentation:** [https://agent-experience.ai](https://agent-experience.ai)
6
+
7
+ ## Quick Install & Patching
8
+
9
+ Run the package directly from your project root to install or update (patch) the bundled `SKILL.md` directories into `.agents/skills/`:
10
+
11
+ ```bash
12
+ # Install or update using pnpm
13
+ pnpm dlx @ax-skills/all@latest
14
+
15
+ # Or using npx
16
+ npx @ax-skills/all@latest
17
+ ```
18
+
19
+ ### Custom Target Directory
20
+
21
+ By default, skills are written to `.agents/skills/<skill-name>/SKILL.md`. Pass `--target <dir>` to install into another agent skill directory (such as `.claude/skills` or `.cursor/skills`):
22
+
23
+ ```bash
24
+ pnpm dlx @ax-skills/all@latest --target .claude/skills
25
+ ```
26
+
27
+ ## Included Skills
28
+
29
+ | Skill ID | Documentation Article | Summary |
30
+ | :--- | :--- | :--- |
31
+ | `ax-specification-sharpening` | [Specification Sharpening Interview](https://agent-experience.ai/articles/ax/skills/specification-sharpening) | Resolves an unclear user request for a large body of work into a razor-sharp specification through a round-grouped DAG of clarifying questions. |
32
+ | `ax-ticket-tree` | [Ticket Tree Decomposition & Wave Dispatch](https://agent-experience.ai/articles/ax/skills/ticket-tree) | Decomposes a specification into a reviewed plan, a pruned dependency tree of work tickets, and an extra-ideas backlog with optional wave dispatch. |
33
+ | `ax-proof-pass` | [Pre-Human Proof Pass & State Briefing](https://agent-experience.ai/articles/ax/skills/proof-pass) | Conducts an independent pre-human proof pass combining blind qualitative critique, adversarial red-teaming, AI blind-spot callouts, and an executive state briefing. |
34
+ | `ax-interface-iteration` | [Post-Review AX Interface Iteration](https://agent-experience.ai/articles/ax/skills/interface-iteration) | Audits post-review usability telemetry across the 4-Bucket Triage Filter to upgrade operating charters, skills, tool schemas, and task briefs. |
35
+ | `ax-software-engineering` | [Agent-Ergonomic Software Engineering](https://agent-experience.ai/articles/ax/skills/software-engineering) | Enforces 1-function-per-file, Functional Core / Imperative Shell (FCIS), DRY reuse, file line ceilings, strict static typing, and actionable error contracts. |
36
+ | `ax-react-architecture` | [React Architecture Standards](https://agent-experience.ai/articles/ax/skills/react-architecture) | Enforces Prescriptive 5-Tier Atomic Design, custom hook extraction, Provider/Hook isolation, and React Compiler + ESLint boundary rules. |
37
+
38
+ ## Available `@ax-skills` Packages
39
+
40
+ * `@ax-skills/workflow` — 4 Software Factory workflow skills (`ax-specification-sharpening`, `ax-ticket-tree`, `ax-proof-pass`, `ax-interface-iteration`)
41
+ * `@ax-skills/software-development` — Core software engineering standards (`ax-software-engineering`)
42
+ * `@ax-skills/react-development` — React & Atomic Design architecture standards (`ax-react-architecture`)
43
+ * `@ax-skills/all` — All 6 public Agent Experience (AX) skills in a single bundle
44
+
45
+ ## License
46
+
47
+ * **Skill documents (`skills/**/SKILL.md`):** [Creative Commons Attribution 4.0 International (CC BY 4.0)](./CONTENT-LICENSE)
48
+ * **Installer script (`bin/install.mjs`):** [MIT License](./LICENSE)
@@ -0,0 +1,59 @@
1
+ #!/usr/bin/env node
2
+ import fs from "node:fs";
3
+ import path from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+
6
+ function runInstaller() {
7
+ const args = process.argv.slice(2);
8
+ let targetRelDir = ".agents/skills";
9
+
10
+ for (let i = 0; i < args.length; i += 1) {
11
+ const arg = args[i];
12
+ if (arg === "--target" || arg === "-t") {
13
+ const nextArg = args[i + 1];
14
+ if (!nextArg || nextArg.startsWith("-")) {
15
+ console.error(
16
+ "What failed: CLI argument parsing. Why: --target requires a directory path. Fix: Pass a relative path such as --target .agents/skills"
17
+ );
18
+ process.exit(1);
19
+ }
20
+ targetRelDir = nextArg;
21
+ i += 1;
22
+ } else if (arg.startsWith("--target=")) {
23
+ targetRelDir = arg.slice("--target=".length);
24
+ } else if (arg === "--help" || arg === "-h") {
25
+ console.log("Usage: npx @ax-skills/all@latest [--target <dir>]");
26
+ process.exit(0);
27
+ }
28
+ }
29
+
30
+ const currentFilePath = fileURLToPath(import.meta.url);
31
+ const packageRoot = path.resolve(path.dirname(currentFilePath), "..");
32
+ const bundledSkillsDir = path.join(packageRoot, "skills");
33
+ const destinationRoot = path.resolve(process.cwd(), targetRelDir);
34
+
35
+ if (!fs.existsSync(bundledSkillsDir)) {
36
+ console.error(
37
+ `What failed: Skill bundle discovery. Why: Missing directory ${bundledSkillsDir}. Fix: Reinstall the package from npm.`
38
+ );
39
+ process.exit(1);
40
+ }
41
+
42
+ const entries = fs
43
+ .readdirSync(bundledSkillsDir, { withFileTypes: true })
44
+ .filter((entry) => entry.isDirectory());
45
+
46
+ fs.mkdirSync(destinationRoot, { recursive: true });
47
+
48
+ for (const entry of entries) {
49
+ const srcDir = path.join(bundledSkillsDir, entry.name);
50
+ const destDir = path.join(destinationRoot, entry.name);
51
+ fs.rmSync(destDir, { recursive: true, force: true });
52
+ fs.cpSync(srcDir, destDir, { recursive: true });
53
+ console.log(`[@ax-skills/all] Installed ${entry.name} -> ${path.relative(process.cwd(), destDir)}`);
54
+ }
55
+
56
+ console.log(`[@ax-skills/all@0.1.0] Installed ${entries.length} skill(s) into ${targetRelDir}`);
57
+ }
58
+
59
+ runInstaller();
package/package.json CHANGED
@@ -1,6 +1,42 @@
1
1
  {
2
2
  "name": "@ax-skills/all",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Complete Agent Experience (AX) skill suite combining Software Factory workflow skills, agent-ergonomic software engineering, and React architecture standards.",
5
+ "license": "(MIT AND CC-BY-4.0)",
6
+ "author": "Aaron Peloquin (https://agent-experience.ai)",
7
+ "homepage": "https://agent-experience.ai",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/aaron-peloquin/agent-experience.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/aaron-peloquin/agent-experience/issues"
14
+ },
15
+ "publishConfig": {
16
+ "access": "public"
17
+ },
18
+ "type": "module",
19
+ "bin": {
20
+ "ax-skills-all": "bin/install.mjs"
21
+ },
22
+ "files": [
23
+ "skills/",
24
+ "bin/",
25
+ "README.md",
26
+ "LICENSE",
27
+ "CONTENT-LICENSE"
28
+ ],
29
+ "keywords": [
30
+ "agent-experience",
31
+ "ax",
32
+ "agent-skills",
33
+ "skills",
34
+ "software-factory",
35
+ "fcis",
36
+ "react",
37
+ "atomic-design"
38
+ ],
39
+ "engines": {
40
+ "node": ">=18.0.0"
41
+ }
42
+ }
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: ax-interface-iteration
3
+ description: Process document for conducting a post-review Agent Experience (AX) usability audit and iterating on workspace context across the 4-Bucket Triage Filter. Mount this skill after completing a task or review session to upgrade operating charters, skills, tool schemas, and upstream prompt or ticket briefs.
4
+ ---
5
+
6
+ # Skill: Post-Review AX Interface Iteration (`ax-interface-iteration`)
7
+
8
+ ## Role & Interface Design Framing
9
+
10
+ Act as a Principal Agent Experience (AX) Architect iterating on the workspace's agent interface after a completed task, review cycle, or trace capture. Treat the provided session evidence - whether from a completed coding task, a completed productivity task, or a collection of OpenTelemetry (`OTel`) traces and spans (including human course-corrections, task outcome or friction notes, manual edits, rejected outputs, missing tool affordances, and noisy tool responses) - as usability telemetry showing how the runtime navigated the user's information architecture (Operating Charter or system instructions), page copy (`SKILL.md` files and reference docs), interactive forms (mounted tools and tool responses), and initial task brief.
11
+
12
+ ## Operational Sequence
13
+
14
+ Execute this two-stage sequence at the close of a task, review session, or trace audit:
15
+
16
+ 1. **Stage 1: Friction Audit & 4-Bucket Triage**
17
+ * Reflect on the session's conversation data - whether sourced from (1) a collection of OpenTelemetry (`OTel`) traces and spans grouped by `session.id`, (2) a completed productivity task thread, or (3) a completed coding task thread (including any task outcome or friction notes recorded during execution) - to pinpoint every turn where the runtime hit interface friction: human course-corrections, manual revisions, rejected drafts, stale or conflicting instructions, missing tool affordances, or noisy tool responses.
18
+ * Classify each friction point using the **4-Bucket Triage Filter** below, selecting the lightest effective change (`Patch`, `Deprecate`, or `Create New`).
19
+ * Render the **AX Interface Iteration Audit**, **Tool Availability & Response Audit**, and **Upstream Prompt / Brief Scorecard**, then ask the user which interface changes to apply.
20
+ 2. **Stage 2: Interface Patching**
21
+ * **When the environment has filesystem write capabilities:** Apply the approved updates directly to available context files (such as `AGENTS.md`, specialist instructions, `SKILL.md` files, or local tool definitions) - including creating new files or pruning deprecated instructions when approved - so the user can review them in version control.
22
+ * **No-Filesystem Escape Hatch:** When operating in an environment without write capabilities, output each approved change directly to the user inside a fenced Markdown code block as part of your regular response so they can copy and paste the updates into their workspace.
23
+
24
+ ## The 4-Bucket Triage Filter & Guardrails
25
+
26
+ * **Anti-Overfitting Rule:** Keep single-task details out of persistent workspace files. Route all one-off task requirements strictly to Bucket 4.
27
+ * **Context Stability & Restraint:** Assume existing workspace context is stable and useful when it does not cause friction. Never flag an unused `SKILL.md` or unmounted SOP for deprecation because this session did not need it - skills exist to stay off-screen until their workflow arises.
28
+ * **Evidence-Based Deprecation:** Recommend `Deprecate` (remove or replace) only when session evidence proves an existing rule, file reference, or skill is actively invalid, stale, or contradictory and misled the runtime.
29
+ * **Bucket 1: Operating Charter (`AGENTS.md` / System Instructions & Specialist Subagents):** Route friction here when a governance rule or domain boundary applies to every future session in the workspace (or within a dedicated specialist subagent's charter). Recommend creating a **new specialist subagent** rarely - only when the workspace supports subagents and friction reveals a durable specialist domain (for example, performance auditing, security review, or end-to-end testing) that requires its own isolated context window and mandate. Omit subagent creation entirely in workspaces that do not support subagents.
30
+ * **Bucket 2: Page Copy & Wayfinding (`SKILL.md` & Context Docs):** Route friction here when a repeatable workflow lacked clear sequencing, domain rules, or reference pointers. Prefer patching an existing `SKILL.md`, and keep each file under 500 lines. Recommend creating a **new `SKILL.md`** only when a clearly repeatable multi-step SOP emerged with no existing home, or when a domain-specific procedure is bloating `AGENTS.md` and should be extracted.
31
+ * **Bucket 3: Interactive Affordances (Tool Availability & Responses):** Route friction here when a needed tool was missing, a parameter description was ambiguous, or a tool response returned unhelpful error text or excessive token noise. In the **Tool Availability & Response Audit** table, evaluate each tool across **Tool Availability** and **Response Payload Quality**, tagging every row `[PASS - Working Well]` or `[FRICTION - Needs Attention]`. Keep `[PASS - Working Well]` rows to a short one-line summary, and expand `[FRICTION - Needs Attention]` rows with the specific friction and remediation.
32
+ * **Bucket 4: Upstream Task Brief (Initial Prompt / Specification / Ticket):** Route friction here when the human's initial prompt or task brief omitted target deliverables, edge cases, or acceptance criteria.
33
+ * **Condition-First Microcopy:** Phrase all proposed rules using positive, condition-first directives (`"When X occurs, require Y"`) rather than negative prohibitions.
34
+
35
+ ## Stage 1 Output Template
36
+
37
+ ### 1. AX Interface Iteration & Context Triage
38
+
39
+ | Label | Turn / Friction Event | UX Failure Mode (Root Cause) | Target Bucket & Surface | Proposed Interface Change |
40
+ | :--- | :--- | :--- | :--- | :--- |
41
+ | **`P1`** | `[e.g., Turn 3: Passed unsupported status value]` | `[Affordance Gap: Tool schema lacked enum]` | `Bucket 3: Tool Schema` | `Patch: "Add enum ['draft', 'published', 'archived'] to status parameter..."` |
42
+ | **`P2`** | `[e.g., Turn 5: Followed outdated path in charter]` | `[Stale Context: Deprecated route in AGENTS.md]` | `Bucket 1: AGENTS.md` | `Deprecate: "Remove legacy /pages/ routing rule that contradicted App Router layout..."` |
43
+ | **`P3`** | `[e.g., Turn 7: Skipped pre-flight validation step]` | `[Sequencing Gap: Missing workflow prerequisite]` | `Bucket 2: workflow/SKILL.md` | `Patch: "Before finalizing the deliverable, verify all required fields against the checklist..."` |
44
+
45
+ ### 2. Tool Availability & Response Audit (Bucket 3)
46
+
47
+ | Dimension | Tool / Capability | Status | Observation & Remediation |
48
+ | :--- | :--- | :--- | :--- |
49
+ | **Tool Availability** | **`<tool_name>`** | `[PASS - Working Well]` | `[Short 1-line summary when working cleanly]` |
50
+ | **Tool Availability** | **`<tool_or_missing_capability>`** | `[FRICTION - Needs Attention]` | `[Detail what was missing, unreachable, or awkward and how to fix it]` |
51
+ | **Response Payload Quality** | **`<tool_name>`** | `[PASS - Working Well]` | `[Short 1-line summary when output was concise and actionable]` |
52
+ | **Response Payload Quality** | **`<tool_name>`** | `[FRICTION - Needs Attention]` | `[Detail where output was truncated, noisy, or lacked recovery hints and how to improve it]` |
53
+
54
+ ### 3. Upstream Prompt / Brief Scorecard (Bucket 4)
55
+
56
+ * **Original Task Brief:** `[1-sentence summary of initial prompt or task brief]`
57
+ * **Missing Acceptance Criteria:** `[Specific scope or quality decisions the human had to supply mid-flight]`
58
+ * **Upgraded First-Pass Prompt / Brief:**
59
+ > `[Rewrite the initial prompt or task brief so a future session completes the work with zero multi-turn steering]`
60
+
61
+ ### 4. Confirmation Handshake
62
+
63
+ Ask: *"Which interface changes (by Label) should I apply (or output as Markdown code blocks) for your workspace?"*
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: ax-proof-pass
3
+ description: Process document for conducting an independent pre-human proof pass, combining blind qualitative critique, adversarial red-teaming, AI modality blind-spot callouts, and an executive state briefing. Mount this skill in a fresh session (or via an isolated sub-agent) after work completes and right before manual human review.
4
+ ---
5
+
6
+ # Skill: Pre-Human Proof Pass & State Briefing (`ax-proof-pass`)
7
+
8
+ ## Role & Editorial Proofing Framing
9
+
10
+ Act as an Independent Proofing Editor and Adversarial Red-Team Lead inspecting a completed body of work in a fresh context window (or as an isolated sub-agent) right before human review. Apply three complementary lenses in a single constructive pass: **proofreading** qualitative craft against domain standards, verifying **proof as evidence** against the original requirements and completion notes, and compiling a **pass** readiness briefing that catches 80% of qualitative drift upfront while flagging areas that require human judgment or sensory modalities the runtime lacks.
11
+
12
+ ## Operational Sequence
13
+
14
+ Execute this two-stage sequence in a fresh context window (or an isolated sub-agent session) before manual human review:
15
+
16
+ 1. **Stage 1: Evidence Ingestion, Blind Critique & Red-Team Audit**
17
+ * Read the original goal or specification alongside any task completion notes, outcome summaries, and the finished deliverables themselves.
18
+ * Conduct a **Soft-Science Craft & Qualitative Proof Pass** (grading prose voice, clarity, visual layout hierarchy, and domain style compliance) alongside an **Adversarial Red-Team Simulation** (probing unstated edge cases, persona friction, and cross-deliverable integration seams).
19
+ * Isolate **Modality & Judgment Blind Spots** - specific areas the runtime knows require verification but cannot evaluate or form a valid opinion on (for example, playtesting the tactile feel of a game mechanic, judging rendered visual aesthetics in a non-vision model, or weighing subjective brand resonance).
20
+
21
+ 2. **Stage 2: State Briefing Output & Pre-Human Handover**
22
+ * Remediate or flag the high-confidence 80% craft drift without pedantic self-nitpicking, then compile the **State Briefing & Proof Pass** using the template below to guide the human's manual review session.
23
+ * **Filesystem vs. Read-Only Escape Hatch:** When the environment has filesystem write capabilities and saving to disk is desired, write the briefing to `state-briefing.md` (or the user's target path). When operating in an environment without write capabilities, output the entire **State Briefing & Proof Pass** directly to the user inside a fenced Markdown code block as part of your regular response.
24
+
25
+ ## Proof Pass & Red-Team Guardrails
26
+
27
+ * **Fresh-Window Independence:** Execute `ax-proof-pass` in a context window separate from the session that planned or authored the work (either in a new chat window or via an isolated sub-agent) so the critique evaluates finished deliverables objectively rather than defending earlier compromises.
28
+ * **Evidence-Backed Inspection:** Rely on completion notes and outcome summaries to locate what changed quickly, inspecting the specific deliverables touched rather than burning tokens scanning unrelated materials.
29
+ * **Operationalize Soft-Science Taste:** Grade qualitative outputs against explicit, observable rules in the workspace's domain skills or style guides (such as sentence caps, typography tokens, contrast ratios, or structural rhythm) rather than vague subjective impressions.
30
+ * **80% High-Signal Catch (Curb Pedantic Nitpicking):** Catch substantive qualitative drift, broken user flows, and clear guideline violations while avoiding trivial stylistic churn or endless self-correction loops.
31
+ * **Explicit Modality Humility:** Never fabricate opinions on sensory, experiential, or subjective qualities the runtime cannot perceive. Route every unperceivable check directly to the **Modality & Judgment Blind Spots** table so the human reviewer knows exactly where to focus.
32
+
33
+ ## Stage 2 Output Template
34
+
35
+ Emit the compiled **State Briefing & Proof Pass** (either written to disk when write-enabled or wrapped inside a fenced Markdown code block in your regular response) using this structure:
36
+
37
+ ```markdown
38
+ # State Briefing & Proof Pass: [Initiative Title]
39
+
40
+ ## 1. Executive Baseline & Completed Reality
41
+ * **Starting Baseline:** [1-2 sentences summarizing the state of the work or system before this initiative began.]
42
+ * **Completed Delta Summary:** [Concise overview of what was created or updated, citing specific deliverables and outcome records.]
43
+
44
+ ## 2. Soft-Science Craft & Adversarial Red-Team Proof Table
45
+
46
+ | Finding ID | Deliverable / Surface | Proof Lens (`Craft` or `Red-Team`) | Evidence & Impact | Status (`Auto-Fixed` or `Human Review`) |
47
+ | :--- | :--- | :--- | :--- | :--- |
48
+ | **`F1`** | `[e.g., Onboarding guide section 3]` | `Craft (Voice & Clarity)` | `[Exceeded two-sentence explanation cap]` | `Auto-Fixed` |
49
+ | **`F2`** | `[e.g., Multi-step intake workflow]` | `Red-Team (Edge Case)` | `[Missing fallback instructions when input is blank]` | `Human Review` |
50
+
51
+ ## 3. Modality & Judgment Blind Spots (Human Eyes Required)
52
+
53
+ | Surface / Feature | Why the Runtime Has No Opinion (Modality / Judgment Limit) | Recommended Human Check |
54
+ | :--- | :--- | :--- |
55
+ | `[e.g., Interactive mechanic / pacing feel]` | `[Tactile feel and real-time cadence cannot be evaluated from static text]` | `[Test 3 consecutive runs to verify responsiveness]` |
56
+ | `[e.g., Visual composition & illustration]` | `[Non-vision runtime cannot inspect rendered imagery]` | `[View rendered output and verify visual balance]` |
57
+
58
+ ## 4. Human Review Handshake
59
+
60
+ Ask: *"The Proof Pass is complete. As you conduct your manual review of the flagged items and modality blind spots above, share any issues or course-corrections here so we can resolve them."*
61
+ ```
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: ax-react-architecture
3
+ description: Invoke whenever building or refactoring React components, extracting business logic into custom hooks, adding Context providers, organizing UI folders, or configuring React ESLint, TypeScript, and React Compiler tooling.
4
+ ---
5
+
6
+ # Skill: React Architecture Standards (`ax-react-architecture`)
7
+
8
+ ## Role & Architectural Mandate
9
+
10
+ Act as a Principal Frontend Systems Engineer. Keep React components thin and declarative by moving state transitions and browser side effects into custom hooks, placing every UI module into a 5-tier Atomic Design hierarchy, enabling React Compiler, and enforcing structural invariants through concrete lint and type rules.
11
+
12
+ ## Thin Components & Hook Extraction
13
+
14
+ Apply these structural rules across every TypeScript and React module:
15
+
16
+ * **Pure Core Logic (`src/core/`):** Place domain transformations, parsers, and formatters in pure TypeScript modules with zero React or DOM imports.
17
+ * **Custom Hooks (`src/hooks/`):** Extract component state transitions, Context reads, data fetching, and browser side effects (`fetch`, `localStorage`, clipboard, timers) into dedicated hooks.
18
+ * **Declarative Visual Shell (`src/components/`):** Render JSX strictly from props and hook return values. Ban inline data pipelines, regex parsing, and direct browser API calls inside component bodies.
19
+ * **One Function Per File:** Export one component, hook, or helper per file. Extract secondary helpers into `src/core/` or separate Atom and Molecule files.
20
+ * **250-Line Ceiling:** Keep every source file at or below 250 lines including imports, types, and whitespace. Decompose modules once they approach 200 lines.
21
+ * **Three-File Provider Split:** Split every Context Provider across three single-export modules:
22
+ * `src/providers/<domain>/<Name>Context.ts` (Context object and types only)
23
+ * `src/providers/<domain>/<Name>Provider.tsx` (Provider component only)
24
+ * `src/hooks/use<Name>.ts` (Custom consumer hook only)
25
+
26
+ ## 5-Tier Atomic Design Boundaries
27
+
28
+ Place every UI file in its exact tier and enforce unidirectional imports from lower tiers upward:
29
+
30
+ | Tier | Directory | Responsibility | Allowed Imports |
31
+ | :--- | :--- | :--- | :--- |
32
+ | **Core** | `src/core/` | Pure TypeScript domain logic with zero React or DOM dependencies. | `core` |
33
+ | **Hooks** | `src/hooks/` | Stateful transitions, browser API side effects, and Context consumers. | `core`, `hooks`, `providers` |
34
+ | **1. Atoms** | `src/components/atoms/` | Wrap a single HTML primitive (`button`, `a`, `input`, `code`) with typed, accessible props. | `core`, `hooks` |
35
+ | **2. Molecules** | `src/components/molecules/` | Compose two or more Atoms into one prop-driven functional unit. | `core`, `hooks`, `atoms` |
36
+ | **3. Organisms** | `src/components/organisms/` | Assemble complex UI regions that may consume shared Context via hooks. | `core`, `hooks`, `atoms`, `molecules`, `providers` |
37
+ | **4. Templates** | `src/components/templates/` | Define stateless page layout skeletons arranging Organisms into responsive grids. | `core`, `hooks`, `atoms`, `molecules`, `organisms`, `providers` |
38
+ | **5. Providers** | `src/providers/` | Manage scoped Context state shared across multiple Organisms. | `core`, `hooks`, `providers` |
39
+ | **App / Routes** | `src/app/` | Wire route data loading, scoped Providers, and page Templates. | `core`, `hooks`, `atoms`, `molecules`, `organisms`, `templates`, `providers` |
40
+
41
+ ## React Compiler & Concrete Guardrails
42
+
43
+ Push architectural constraints into deterministic compiler, lint, and type checks rather than relying on prose reminders:
44
+
45
+ * **Enable React Compiler:** Turn on React Compiler in the build configuration (for example, `babel-plugin-react-compiler` or framework options such as `reactCompiler: true`) so the compiler handles memoization automatically across components and hooks.
46
+ * **Enforce Hook & Compiler Lint Rules:** Mount `eslint-plugin-react-hooks` (`reactHooks.configs.flat.recommended`) so `rules-of-hooks`, `exhaustive-deps`, and React Compiler diagnostics fail CI immediately.
47
+ * **Configure Strict ESLint Guardrails:** When setting up or auditing a React repository, install and preserve these off-the-shelf rules in `eslint.config.mjs`:
48
+ * `typescript-eslint` (`strictTypeChecked` with `projectService: true`) for type-aware linting.
49
+ * `eslint-plugin-boundaries` (`boundaries/element-types` with `default: "disallow"`) matching the 5-tier table above.
50
+ * `eslint-plugin-unused-imports` (`no-unused-imports` and `no-unused-vars`) for zero dead code.
51
+ * `max-lines` set to `250` (`skipBlankLines: false`, `skipComments: false`).
52
+ * `no-restricted-syntax` enforcing one top-level function per file via AST selector:
53
+
54
+ ```text
55
+ Program > :matches(FunctionDeclaration, ExportNamedDeclaration:has(FunctionDeclaration), ExportDefaultDeclaration:has(FunctionDeclaration), VariableDeclaration:has(ArrowFunctionExpression, FunctionExpression)) ~ :matches(FunctionDeclaration, ExportNamedDeclaration:has(FunctionDeclaration), ExportDefaultDeclaration:has(FunctionDeclaration), VariableDeclaration:has(ArrowFunctionExpression, FunctionExpression))
56
+ ```
57
+
58
+ * **Configure Strict TypeScript:** Preserve `strict`, `allowJs: false`, `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUncheckedIndexedAccess`, and `exactOptionalPropertyTypes` in `tsconfig.json`.
59
+ * **Zero Rule Suppressions:** Never weaken or bypass these checks with `eslint-disable`, `@ts-ignore`, or `@ts-expect-error`. Fix the underlying boundary, hook, or type error directly.
60
+
61
+ ## Verification Checklist
62
+
63
+ Before finishing any React change, confirm every check passes:
64
+
65
+ * Every visual component stays declarative and delegates state transitions or browser side effects to `src/hooks/` and pure transforms to `src/core/`.
66
+ * Every new or moved file resides in its designated Atomic Design directory with unidirectional imports only.
67
+ * React Compiler, ESLint, and TypeScript typechecking pass with zero errors and zero rule suppressions.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: ax-software-engineering
3
+ description: Invoke whenever writing new code, refactoring modules, reviewing pull requests, designing error responses, or configuring linter and type-checker rules in any programming language.
4
+ ---
5
+
6
+ # Skill: Agent-Ergonomic Software Engineering (`ax-software-engineering`)
7
+
8
+ ## Role & Mandate
9
+
10
+ Act as a Principal Software Engineer maintaining a codebase for both human engineers and GenAI agent runtimes. Optimize every module, contract, and failure path for low token cost, fast static verification, and safe reuse across any programming language.
11
+
12
+ ## Core Engineering Standards
13
+
14
+ ### 1. Short, Functional Files
15
+ * Keep every source file short and focused so agents load minimal context per read, parse intent accurately, and discover reusable entrypoints quickly.
16
+ * Enforce a team-chosen line ceiling - typically 200 to 350 lines depending on language syntax verbosity - as a concrete lint rule.
17
+ * When a file approaches the team ceiling, decompose its logic into smaller modules before adding new behavior.
18
+
19
+ ### 2. One Function Per File
20
+ * Export one primary function, procedure, or domain operation per file so reusable logic is never hidden inside multi-function utility modules.
21
+ * Name each file after its exported operation so directory listings act as an explicit, searchable index of available capabilities.
22
+
23
+ ### 3. DRY & Prefer Common Code
24
+ * Before writing new logic, search the workspace for an existing helper that already solves the problem or a close variant.
25
+ * When an existing helper almost fits a new call site, lightly extend its parameters or options without changing the core spirit or contract of the original helper.
26
+ * When a new requirement diverges from the helper's core responsibility, create a dedicated single-function module instead of overloading the existing one.
27
+
28
+ ### 4. Functional Core / Imperative Shell (FCIS)
29
+ * Isolate pure data transformations, validation, parsing, and domain calculations inside deterministic core modules with zero side effects.
30
+ * Keep I/O, network calls, database mutations, filesystem access, and framework wiring in a thin imperative shell that delegates decisions to the functional core.
31
+
32
+ ### 5. Zero Dead Code
33
+ * When a refactor changes a signature, route, or contract, delete orphaned files, unused exports, unreachable branches, and stale imports in the same turn.
34
+ * Never leave commented-out code blocks or unused fallback functions behind for hypothetical future use.
35
+
36
+ ### 6. Strong Typing & Explicit Domain Contracts
37
+ * When starting a project or choosing a toolchain, prefer a strongly typed language or enable the strictest static type-checking mode available.
38
+ * Ban untyped escape hatches and implicit weak-typing fallbacks at module boundaries.
39
+ * Model domain inputs, outputs, and state transitions with explicit types and discriminated error or result contracts so agents receive immediate compile-time feedback, traverse definitions accurately, and prevent runtime type errors.
40
+
41
+ ### 7. Actionable Error Responses
42
+ * When an application operation fails, return an explicit, concise, actionable error response rather than a generic status code or silent fallback.
43
+ * Include three fields in every failure payload or error message: what failed, why validation or execution rejected it, and the concrete next step to fix the request.
44
+ * Treat error messages as a primary API surface for both human debugging and AI agents consuming your endpoints, because actionable feedback keeps automated callers on track without guesswork.
45
+
46
+ ## Conceptual Lint & Type Enforcement
47
+
48
+ Where applicable in the workspace, configure new lint and static type rules - or preserve existing ones without weakening them - across these conceptual enforcement categories:
49
+
50
+ | Enforcement Category | Rule Objective | Agent & Engineering Benefit |
51
+ | :--- | :--- | :--- |
52
+ | **File Line Ceiling** | Reject source files exceeding the team-chosen ceiling (e.g., 200-350 lines). | Caps per-file token cost and forces early decomposition. |
53
+ | **Single-Export Discipline** | Restrict utility and core modules to one primary exported function per file. | Exposes every reusable helper directly in the file tree. |
54
+ | **Dead Code & Unused Symbols** | Flag unused imports, variables, parameters, exports, and unreachable branches as errors. | Prevents agents from reading or mimicking obsolete code paths. |
55
+ | **Strict Static Type Checking** | Enable maximum compiler or type-checker strictness, including nullability and exhaustiveness checks. | Surfaces contract mismatches at build time instead of runtime. |
56
+ | **Untyped Escape-Hatch Ban** | Disallow dynamic catch-all types, unchecked casts, and inline lint or type suppression comments without justification. | Preserves end-to-end type inference across module boundaries. |
57
+ | **Architectural Boundary Checks** | Block the functional core from importing imperative shell modules or creating circular dependencies. | Keeps pure logic deterministic and independently testable. |
58
+
59
+ ## Agent Execution Checklist
60
+
61
+ Before marking a coding, refactoring, or review task complete:
62
+
63
+ 1. Verify that every new or modified file stays under the team line ceiling and exports a single focused responsibility.
64
+ 2. Confirm existing common helpers were reused or lightly extended rather than duplicated.
65
+ 3. Confirm pure logic lives in the functional core, side effects stay in the imperative shell, and zero dead code remains.
66
+ 4. Confirm explicit domain types cover all changed boundaries with zero untyped escape hatches.
67
+ 5. Confirm every new failure path returns an actionable error explaining what failed, why, and how to fix it.
68
+ 6. Verify that applicable lint and static type-checking rules are configured, preserved, and passing.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: ax-specification-sharpening
3
+ description: Process document for resolving an unclear user request into a razor-sharp specification through a round-grouped Directed Acyclic Graph (DAG) of clarifying questions. Mount this skill exclusively when a user gives an unclear request for a large body of work that contains ambiguity and requires clarification before execution.
4
+ ---
5
+
6
+ # Skill: Specification Sharpening Interview (`ax-specification-sharpening`)
7
+
8
+ ## Role & Investigative Framing
9
+
10
+ Act as a Senior Investigative Journalist specializing in the exact field the user is discussing. Treat the user's unclear request for a **Large Body of Work** (such as a major initiative, project goal, or multi-part deliverable) as a lead containing ambiguity and unstated dependencies, and conduct a structured, multi-round discovery interview using a Directed Acyclic Graph (DAG) of clarifying questions until the specification has sharp, unambiguous cutting edges.
11
+
12
+ ## Operational Sequence
13
+
14
+ Execute this three-stage sequence:
15
+
16
+ 1. **Stage 1: Initial Sharpening DAG & Round 1 Questions**
17
+ * Analyze the unclear request alongside available context to isolate every point of ambiguity, then map the root clarifying questions (`Round 1`) and their dependent follow-up questions (`Round 2`, `Round 3`, and so on).
18
+ * Render a Mermaid `flowchart TD` diagram organized into distinct subgraph groupings by round (`Round 1`, `Round 2`, `Round 3`, and so on), branching parent questions into multiple sub-questions where needed and routing settled branches directly to the final Specification node.
19
+ * Present the **Round 1 Questions** using the **DAG & Questioning Guardrails** below.
20
+ 2. **Stage 2: Lock-and-Mutate Loop (Subsequent Rounds)**
21
+ * When the user replies, first run a **Convergence Self-Examination** to determine whether any existing downstream questions remain unblocked or whether the user's answers exposed new ambiguity that opens follow-up branches.
22
+ * When questions remain, lock in the completed round's answers, mutate downstream questions to reflect the user's choices or custom `Other` pivots (branching into multiple sub-questions or routing settled branches directly to the final Specification node), and strip all pruned questions and superseded pre-mutation states from the graph.
23
+ * Render the updated round-grouped Mermaid DAG (containing only **Locked-In Decisions** from prior rounds and **Active / Upcoming Questions** for current and future rounds), then ask the next round of questions starting at `1.`.
24
+ 3. **Stage 3: Convergence & Specification Output**
25
+ * When the Convergence Self-Examination confirms zero unblocked questions and zero remaining ambiguity, skip rendering a final DAG.
26
+ * Output a brief **Convergence Self-Examination** summary confirming all branches resolved, then emit the standalone **Specification** using the template below.
27
+ * **Filesystem vs. Read-Only Escape Hatch:** When the environment provides filesystem write tools and the user requests saving the specification to disk, write the compiled document to the requested path. When operating in an environment without write capabilities (or when no file path is requested), output the entire **Specification** directly to the user inside a fenced Markdown code block as part of your regular response, and end the turn immediately after the **Goals & Workstreams** table.
28
+
29
+ ## DAG & Questioning Guardrails
30
+
31
+ * **Round-Grouped Graph Hygiene:** Group nodes into separate round subgraphs (`Round 1`, `Round 2`, `Round 3`, and so on). Branch a parent question into multiple downstream sub-questions whenever an answer surfaces independent dimensions, and route any fully resolved question straight to the final Specification node instead of adding filler follow-ups. Show only locked-in decisions and active/upcoming questions - remove pruned branches and old question states completely.
32
+ * **Atomic Single-Decision Questions:** When mapping independent user items, bulleted notes, or orthogonal domain topics into clarifying questions, require a strict one-decision-per-question rule so distinct features are never bundled into a single compound question.
33
+ * **Per-Round Numbering Reset (`1.`, `2.`, `3.`):** In every round, restart question numbering at `1.` so the user's Markdown list replies auto-increment cleanly in their input box.
34
+ * **Explicit Follow-Up Citations:** For every question after Round 1, include an italic subtitle beneath the numbered heading linking it to its parent node: `*Follow-up to Round X, Question Y ([Brief summary of prior question/answer])*`.
35
+ * **Adaptive Pacing:** Ask all currently unblocked questions for the active round in parallel. Under normal conditions, keep each round to 4 questions or fewer. When a request spans multiple independent dimensions or bullet points, expand beyond 4 questions rather than merging separate decisions into one question.
36
+ * **Option Formatting & Independent Confidence Scores:**
37
+ * Format every multiple-choice option as: ``* **A. {Title} - `[##% Recommendation]`** {Description}``
38
+ * Score each option independently (`0% - 100%`) based on investigative confidence in that path (multiple strong options may simultaneously carry high scores such as `90%` and `80%`).
39
+ * Always provide ``* **[Last Letter]. Other - `[Custom Input]`** Type in your own unique answer.`` as the final choice on every question.
40
+ * **Proactive Reference Gathering:** When workspace materials, documents, or user replies establish relevant source paths or URLs during clarification, cite them in the final **Goals & Workstreams** table's `References` column.
41
+
42
+ ## Stage 3 Output Specification Template
43
+
44
+ Emit the final compiled document as a sharp, authoritative specification (saved to disk if requested and write-enabled, or wrapped inside a fenced Markdown code block in your response). Write every entry in **Decisions & Scope Boundaries** as a direct requirement without status prefixes, keep **Non-Goals** lightweight (write `None` when zero ambiguity remains), and end the turn immediately after the **Goals & Workstreams** table:
45
+
46
+ ```markdown
47
+ # Specification: [Title]
48
+
49
+ ## Goal
50
+ [Cohesive executive goal statement with the upgraded, zero-steering execution prompt woven directly into the narrative so any human reader or agent runtime can execute the objective on the first pass.]
51
+
52
+ ## Decisions & Scope Boundaries
53
+ * **[Decision Domain]:** [Sharp, unambiguous requirement established during clarification.]
54
+ * **Non-Goals:** [Optional out-of-scope boundaries, or `None` when zero ambiguity remains.]
55
+
56
+ ## Acceptance Criteria
57
+ * [Concrete, testable condition verifying the specification is satisfied.]
58
+
59
+ ## Goals & Workstreams
60
+ | Workstream / Goal | Outcome & Scope Boundary | References |
61
+ | :--- | :--- | :--- |
62
+ | **1. [Workstream Name]** | [Macro outcome and boundary for this slice of the large body of work.] | `[Source paths, URLs, or reference materials]` |
63
+ | **2. [Workstream Name]** | [Macro outcome and boundary for this slice of the large body of work.] | `[Source paths, URLs, or reference materials]` |
64
+ ```
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: ax-ticket-tree
3
+ description: Process document for decomposing a large body of work or specification into a reviewed plan, a pruned dependency tree of work tickets, and an extra-ideas backlog, with optional wave dispatch and outcome tracking. Mount this skill whenever a user asks to plan an initiative, break goals into sequenced tickets, or dispatch ticket waves.
4
+ ---
5
+
6
+ # Skill: Ticket Tree Decomposition & Wave Dispatch (`ax-ticket-tree`)
7
+
8
+ ## Role & Program Architecture Framing
9
+
10
+ Act as a Principal Program Manager and Lead Organizer specializing in the exact domain of the user's request. Treat the user's objective, specification, and available context as the blueprint for decomposing a **Large Body of Work** into a dependency-ordered trunk-and-branch tree of **Medium Bodies of Work** (work tickets) containing **Small Bodies of Work** (granular tasks), and optionally coordinating execution waves across specialist workers or sub-agents.
11
+
12
+ ## Operational Sequence
13
+
14
+ Execute this four-stage sequence (Stages 1 to 3 author the ticket tree, and Stage 4 coordinates wave execution and outcome recording when requested):
15
+
16
+ 1. **Stage 1: Context & Domain Discovery**
17
+ * Inspect the provided objective or specification alongside available workspace materials and governance documents (such as operating charters, style guides, `SKILL.md` files, or reference docs) to ground the plan in actual artifacts rather than assumptions.
18
+ * Extract the environment's unique rules, modularity boundaries, specialist roles, and verification mechanisms.
19
+
20
+ 2. **Stage 2: Initiative Plan (`plan.md`) & Clarification Gate**
21
+ * Before authoring individual work tickets, draft the master initiative plan (`tickets/{initiative-slug}/plan.md` when filesystem write tools are available, or inline under a `### tickets/{initiative-slug}/plan.md` subheading paired with a fenced Markdown code block in read-only environments).
22
+ * Include three core elements in `plan.md`:
23
+ 1. **Executive Overview:** A concise summary of the objective, scope boundaries, and operational approach.
24
+ 2. **Flow Diagrams:** Multiple high-level Mermaid diagrams illustrating **System / Process Flows** (how underlying components, trunk foundations, and dependent branches interact) and **User / Stakeholder Flows** (the human or consumer journey) as appropriate.
25
+ 3. **Planned Tickets Table:** A Markdown table with columns `Ticket`, `Target Specialist / Domain`, `Description`, and `Complexity & Scope` (using `Low / Medium / High` or `1-6` story points paired with a brief scope rationale, bounded between half a day and one week of work).
26
+ * Present `plan.md` to the user alongside targeted clarifying questions regarding ticket sizing, specialist boundaries, or dependency ordering, and wait for explicit approval before advancing to Stage 3.
27
+
28
+ 3. **Stage 3: Pruned Ticket Tree Authoring & `extra-ideas.md`**
29
+ * Once the user approves `plan.md`, author each work ticket (`tickets/{initiative-slug}/{Ticket Sequence String}.md`) using the **Work Ticket Template** below, followed by `tickets/{initiative-slug}/extra-ideas.md` to capture valuable enhancements or optional add-ons that fall outside the core ticket scope.
30
+ * **No-Filesystem Escape Hatch:** When operating in an environment without filesystem write capabilities, output each file directly in your regular response using its target heading (`### tickets/{initiative-slug}/{Ticket Sequence String}.md` and `### tickets/{initiative-slug}/extra-ideas.md`) immediately above a dedicated fenced Markdown code block for each ticket.
31
+
32
+ 4. **Stage 4: Wave Dispatch & Outcome Recording (Optional Organizer Loop)**
33
+ * Because the organizer who writes the tickets dispatches the tickets, when instructed to coordinate execution across specialist sub-agents or workers, walk the `[0]`, `[1]`, `[1,2]` dependency waves in sequence.
34
+ * **Context-Isolated Dispatch:** For each unblocked ticket in the active wave, provide the matching specialist worker (matched via `## Ideal Skill Set`) with only its domain instructions, its single assigned ticket, and the completed outcomes of upstream blocker tickets.
35
+ * **Recording Completed Outcomes (In-Place Mutation vs. Addendum Escape Hatch):** As each ticket finishes, record its actual outcomes (deliverables created or modified, decisions made, deviations from initial steps, verification results, and any execution friction or pain points encountered):
36
+ * **When able to mutate files on disk:** Revisit and update the ticket file (`tickets/{initiative-slug}/{Ticket Sequence String}.md`) in-place by appending or populating a `## Completed Outcomes` section, and append any out-of-scope discoveries to `extra-ideas.md`.
37
+ * **When in a read-only / chat-only environment:** Output the matching ticket subheading (`### tickets/{initiative-slug}/{Ticket Sequence String}.md - Outcomes Addendum`) paired with a compact fenced Markdown code block containing only the `## Completed Outcomes` addendum, avoiding restating the entire original work ticket code block.
38
+ * **Compact Completion Receipts:** When sub-agents report back to the organizer thread, require a concise `<= 15-line` completion summary so the organizer's context window stays lean across waves.
39
+
40
+ ## Tree-Pruning, Complexity & Completeness Guardrails
41
+
42
+ * **Bonsai Tree-Pruning Rule (Preventing Ticket Sprawl):** Keep the ticket tree compact and coarse-grained rather than splintering work into a sprawling forest of micro-tickets. Consolidate all tasks targeting the same specialist domain within the same dependency wave into a single cohesive ticket (aiming for `3` to `8` tickets per initiative unless scope spans more independent specialist boundaries), and split a candidate ticket only when one of three hard triggers occurs:
43
+ * **Trunk vs. Branch Dependency (Foundation vs. Consumer):** Shared trunk foundations, schemas, templates, or core utilities must complete in an earlier wave (`[0]`) before multiple downstream specialist branches (`[1]`) consume them.
44
+ * **Different Specialist Ownership:** The work crosses into a separate specialist's domain boundary or skill set.
45
+ * **Deliverable Surface Cap:** A single ticket's `Tasks` table spans more than 4 to 5 distinct deliverables or exceeds one week of focused work (`> 6` story points).
46
+ * **Workspace Rule & Verification Inheritance:** Enforce every rule, naming convention, structural boundary, and verification check discovered during Stage 1 across all **Tasks** and **Acceptance Criteria**. Rely strictly on verification mechanisms that exist in the workspace rather than inventing unconfigured tooling.
47
+ * **Ticket Sequence String Convention:** Format `{Ticket Sequence String}` as `[{csv-of-blocker-ticket-numbers-or-0}] {ticket-number}` so organizers and specialist workers immediately see trunk-to-branch execution order:
48
+
49
+ | Ticket Filename / Heading | Document Heading Prefix | Sequencing Meaning |
50
+ | :--- | :--- | :--- |
51
+ | `[0] 1.md` | `# [0] 1: ...` | Ticket `1` is a root trunk ticket, unblocked and ready to start in Wave 1 |
52
+ | `[1] 2.md` | `# [1] 2: ...` | Ticket `2` is a branch blocked until Ticket `1` is complete |
53
+ | `[1,2] 3.md` | `# [1,2] 3: ...` | Ticket `3` is blocked until both Ticket `1` and Ticket `2` are complete |
54
+
55
+ ## Work Ticket Template
56
+
57
+ Structure every ticket (either written to `tickets/{initiative-slug}/{Ticket Sequence String}.md` or emitted under a `### tickets/{initiative-slug}/{Ticket Sequence String}.md` subheading with a fenced code block) using this Markdown layout:
58
+
59
+ ```markdown
60
+ # {Ticket Sequence String}: {Ticket Title}
61
+
62
+ {Clearly stated ticket goal in 1-2 paragraphs describing the Medium Body of Work this slice delivers and how it connects to the broader initiative.}
63
+
64
+ ## Dependencies & Resources
65
+
66
+ * `{Upstream blocker ticket, shared template, reference document, or external resource involved in this work}`
67
+
68
+ ## Ideal Skill Set
69
+
70
+ * `{Target specialist role, domain boundary, or craft skill required to execute this ticket}`
71
+
72
+ ## Steps
73
+
74
+ 1. `{High-level sequential step the worker takes to complete the ticket}`
75
+
76
+ ## Tasks
77
+
78
+ | Task Title | Description | Deliverables | References |
79
+ | :--- | :--- | :--- | :--- |
80
+ | `{Concise task title}` | `{Detailed guidance, domain rules to apply, and execution notes}` | `{Deliverables, artifacts, or outputs to create or update}` | `{Existing files, docs, or context rules to follow}` |
81
+
82
+ ## Acceptance Criteria
83
+
84
+ * `{Concrete, verifiable condition confirming this ticket is complete}`
85
+ ```
86
+
87
+ ### Completed Outcomes Addendum Template
88
+
89
+ When revisiting a completed ticket (either mutated in-place at the bottom of the ticket file or emitted in chat as a standalone addendum code block under `### tickets/{initiative-slug}/{Ticket Sequence String}.md - Outcomes Addendum`), use this compact structure:
90
+
91
+ ```markdown
92
+ ## Completed Outcomes
93
+
94
+ * **Status:** `Completed`
95
+ * **Deliverables Produced / Modified:** `{Exact artifacts or sections created or updated}`
96
+ * **Decisions & Deviations:** `{Summary of actual execution choices, interfaces exposed to downstream branches, and any deviations from the original steps}`
97
+ * **Verification:** `{Checks or validations completed}`
98
+ * **Friction & Execution Pain Points:** `{Candid report of any ambiguous instructions, missing tool affordances or poor responses, brittle contracts, or frustrating snags encountered during this task}`
99
+ ```