@llipe.com/dev-tasks 0.9.2 → 0.11.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.
Files changed (69) hide show
  1. package/.claude/agents/developer.md +11 -0
  2. package/.claude/agents/qa-engineer.md +31 -2
  3. package/.claude/agents/researcher.md +96 -0
  4. package/.claude/agents/ux-engineer.md +118 -114
  5. package/.claude/commands/planner.md +22 -7
  6. package/.claude/commands/product-engineer.md +37 -10
  7. package/.claude/commands/researcher.md +28 -0
  8. package/.claude/skills/activity-codebase-research/SKILL.md +158 -0
  9. package/.claude/skills/activity-contract-validation/SKILL.md +167 -0
  10. package/.claude/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  11. package/.claude/skills/activity-integration-test-implementation/SKILL.md +156 -0
  12. package/.claude/skills/activity-refine/SKILL.md +1 -0
  13. package/.claude/skills/activity-test-standards/SKILL.md +41 -0
  14. package/.claude/skills/ux-scaffold/SKILL.md +129 -0
  15. package/.claude/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  16. package/.claude/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  17. package/.claude/skills/ux-theme-gen/SKILL.md +149 -0
  18. package/.github/agents/developer.agent.md +11 -0
  19. package/.github/agents/planner.agent.md +22 -7
  20. package/.github/agents/product-engineer.agent.md +37 -10
  21. package/.github/agents/qa-engineer.agent.md +30 -3
  22. package/.github/agents/researcher.agent.md +96 -0
  23. package/.github/agents/ux-engineer.agent.md +119 -114
  24. package/.github/prompts/researcher.prompt.md +29 -0
  25. package/.github/skills/activity-codebase-research/SKILL.md +158 -0
  26. package/.github/skills/activity-contract-validation/SKILL.md +167 -0
  27. package/.github/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  28. package/.github/skills/activity-integration-test-implementation/SKILL.md +156 -0
  29. package/.github/skills/activity-refine/SKILL.md +6 -0
  30. package/.github/skills/activity-test-standards/SKILL.md +41 -0
  31. package/.github/skills/ux-scaffold/SKILL.md +129 -0
  32. package/.github/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  33. package/.github/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  34. package/.github/skills/ux-theme-gen/SKILL.md +149 -0
  35. package/.kiro/agents/developer.md +11 -0
  36. package/.kiro/agents/planner.md +22 -7
  37. package/.kiro/agents/product-engineer.md +37 -10
  38. package/.kiro/agents/qa-engineer.md +30 -3
  39. package/.kiro/agents/researcher.md +99 -0
  40. package/.kiro/agents/ux-engineer.md +119 -132
  41. package/.kiro/agents/verifier.md +1 -1
  42. package/.kiro/skills/activity-codebase-research/SKILL.md +158 -0
  43. package/.kiro/skills/activity-contract-validation/SKILL.md +167 -0
  44. package/.kiro/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  45. package/.kiro/skills/activity-integration-test-implementation/SKILL.md +156 -0
  46. package/.kiro/skills/activity-refine/SKILL.md +1 -0
  47. package/.kiro/skills/activity-test-standards/SKILL.md +41 -0
  48. package/.kiro/skills/ux-scaffold/SKILL.md +129 -0
  49. package/.kiro/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  50. package/.kiro/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  51. package/.kiro/skills/ux-theme-gen/SKILL.md +149 -0
  52. package/AGENTS.md +91 -214
  53. package/CHANGELOG.md +64 -0
  54. package/CLAUDE.md +3 -2
  55. package/DESIGN.md +233 -0
  56. package/README.md +31 -28
  57. package/TESTING.md +19 -11
  58. package/bundle-manifest.json +1 -0
  59. package/dist/core/distribution/doctor.d.ts +2 -2
  60. package/dist/core/distribution/doctor.js +3 -3
  61. package/dist/core/distribution/profiles.d.ts.map +1 -1
  62. package/dist/core/distribution/profiles.js +1 -1
  63. package/dist/core/distribution/profiles.js.map +1 -1
  64. package/package.json +4 -3
  65. package/.claude/skills/webapp-mockup/SKILL.md +0 -76
  66. package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
  67. package/.github/skills/webapp-mockup/SKILL.md +0 -71
  68. package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
  69. package/.kiro/skills/webapp-mockup/SKILL.md +0 -76
@@ -0,0 +1,149 @@
1
+ ---
2
+ name: ux-theme-gen
3
+ description: "Generate platform-specific theme artifacts from DESIGN.md. Use when mockups or production code need consumable tokens derived from the canonical design contract."
4
+ ---
5
+
6
+ # UX Theme Generation
7
+
8
+ ## Purpose
9
+
10
+ Transform the YAML front matter in `/DESIGN.md` into consumable theme artifacts that mockups and production code import directly. This eliminates hand-copied colour values and keeps every surface aligned with the declared contract.
11
+
12
+ ## When to Use
13
+
14
+ - Before generating any mockup (Phase 0 of `ux-engineer`).
15
+ - When `developer` needs production theme files aligned with DESIGN.md.
16
+ - After filling or updating DESIGN.md tokens.
17
+ - When a stale theme artifact is detected (its tokens don't match DESIGN.md).
18
+
19
+ ## Inputs
20
+
21
+ | Input | Required | Default |
22
+ | --------------------------------------- | -------- | ------------------ |
23
+ | `/DESIGN.md` | yes | — |
24
+ | `theme_output` path (from front matter) | no | `/mockups/.theme/` |
25
+
26
+ ## Contract Check (Must Run First)
27
+
28
+ Before generating any artifact:
29
+
30
+ 1. Read `/DESIGN.md` front matter.
31
+ 2. If `status: placeholder` → **refuse** with: "DESIGN.md is an unfilled placeholder. Run ux-engineer to fill it first."
32
+ 3. If any `"<unfilled>"` sentinel remains in the token groups (`colors`, `typography`, `rounded`, `spacing`) → **refuse** and list the unfilled fields.
33
+ 4. Resolve `{colors.x}` / `{typography.y}` style references. If a reference points to an unfilled or missing key → **refuse** and report the broken reference.
34
+ 5. Only proceed to generation if all checks pass.
35
+
36
+ ## Outputs
37
+
38
+ Generated into `{theme_output}` (default `/mockups/.theme/`):
39
+
40
+ | File | Content | When |
41
+ | ------------- | ------------------------------------------------------------------ | ------------------------------------------------ |
42
+ | `theme.css` | `:root` token declarations + `@theme inline` block for Tailwind v4 | always |
43
+ | `tokens.json` | Raw JSON: all token groups as a flat or nested object | always |
44
+ | `rn-theme.ts` | TypeScript theme object for React Native | only when `platform` includes `mobile` or `both` |
45
+
46
+ ### `theme.css` structure
47
+
48
+ ```css
49
+ /* DO NOT EDIT — generated from /DESIGN.md by ux-theme-gen */
50
+
51
+ @theme inline {
52
+ --font-sans: "<fontFamily from typography.body-md>";
53
+ --color-background: var(--background);
54
+ --color-foreground: var(--foreground);
55
+ --color-primary: var(--primary);
56
+ --color-primary-foreground: var(--primary-foreground);
57
+ /* ... one --color-* per semantic slot ... */
58
+ --radius-sm: <rounded.sm>;
59
+ --radius-md: <rounded.md>;
60
+ --radius-lg: <rounded.lg>;
61
+ }
62
+
63
+ :root {
64
+ --background: <colors.background>;
65
+ --foreground: <colors.foreground>;
66
+ --primary: <colors.primary>;
67
+ --primary-foreground: <colors.primary-foreground>;
68
+ /* ... all semantic slots ... */
69
+ --radius: <rounded.md>;
70
+ }
71
+
72
+ .dark {
73
+ /* dark-mode overrides if declared in DESIGN.md */
74
+ }
75
+ ```
76
+
77
+ ### Colour handling
78
+
79
+ - Emit colour values **exactly as declared** in DESIGN.md (hex, rgb, hsl, oklch — whatever the consumer wrote).
80
+ - Do **not** convert between colour spaces. `@theme` accepts any valid CSS colour.
81
+ - If DESIGN.md uses hex and the consumer later wants OKLCH, that is a DESIGN.md authoring decision, not a generator decision.
82
+
83
+ ### Slot mapping
84
+
85
+ The semantic slots below are the ones Tailwind v4 + shadcn components consume via `@theme inline`. `ux-theme-gen` maps from DESIGN.md token names to these slots:
86
+
87
+ | DESIGN.md token | CSS variable | @theme inline mapping |
88
+ | ------------------------------- | -------------------------- | --------------------------------------------------------------- |
89
+ | `colors.background` | `--background` | `--color-background: var(--background)` |
90
+ | `colors.foreground` | `--foreground` | `--color-foreground: var(--foreground)` |
91
+ | `colors.primary` | `--primary` | `--color-primary: var(--primary)` |
92
+ | `colors.primary-foreground` | `--primary-foreground` | `--color-primary-foreground: var(--primary-foreground)` |
93
+ | `colors.secondary` | `--secondary` | `--color-secondary: var(--secondary)` |
94
+ | `colors.secondary-foreground` | `--secondary-foreground` | `--color-secondary-foreground: var(--secondary-foreground)` |
95
+ | `colors.muted` | `--muted` | `--color-muted: var(--muted)` |
96
+ | `colors.muted-foreground` | `--muted-foreground` | `--color-muted-foreground: var(--muted-foreground)` |
97
+ | `colors.accent` | `--accent` | `--color-accent: var(--accent)` |
98
+ | `colors.accent-foreground` | `--accent-foreground` | `--color-accent-foreground: var(--accent-foreground)` |
99
+ | `colors.destructive` | `--destructive` | `--color-destructive: var(--destructive)` |
100
+ | `colors.destructive-foreground` | `--destructive-foreground` | `--color-destructive-foreground: var(--destructive-foreground)` |
101
+ | `colors.border` | `--border` | `--color-border: var(--border)` |
102
+ | `colors.input` | `--input` | `--color-input: var(--input)` |
103
+ | `colors.ring` | `--ring` | `--color-ring: var(--ring)` |
104
+ | `colors.card` | `--card` | `--color-card: var(--card)` |
105
+ | `colors.card-foreground` | `--card-foreground` | `--color-card-foreground: var(--card-foreground)` |
106
+
107
+ Tokens in `colors-extended` get their own `--<name>` variable in `:root` and a `--color-<name>` in `@theme inline`.
108
+
109
+ ### `tokens.json` structure
110
+
111
+ ```json
112
+ {
113
+ "colors": { "background": "#...", "foreground": "#...", ... },
114
+ "colors-extended": { ... },
115
+ "typography": { ... },
116
+ "rounded": { "sm": "6px", "md": "8px", "lg": "12px" },
117
+ "spacing": { "xs": "4px", ... }
118
+ }
119
+ ```
120
+
121
+ ### Generated file header
122
+
123
+ Every generated file **MUST** start with:
124
+
125
+ ```
126
+ /* DO NOT EDIT — generated from /DESIGN.md by ux-theme-gen */
127
+ ```
128
+
129
+ (or the equivalent comment syntax for `.ts` / `.json`).
130
+
131
+ ## Rules
132
+
133
+ 1. **Read-only on DESIGN.md** — never modify the contract.
134
+ 2. **Refuse on placeholder** — never generate from unfilled tokens.
135
+ 3. **No colour-space conversion** — emit values as declared.
136
+ 4. **Idempotent** — running twice with the same DESIGN.md produces byte-identical output.
137
+ 5. **Regenerable** — hand-edits to generated files are findings; the correct fix is to update DESIGN.md and regenerate.
138
+ 6. **Independent of mockup workflow** — `developer` can invoke this skill directly for production theming.
139
+
140
+ ## Acceptance Checklist
141
+
142
+ - Contract check runs before any file is written
143
+ - Refuses against a placeholder or partially-unfilled DESIGN.md
144
+ - Generated `theme.css` uses `@theme inline` (Tailwind v4 pattern)
145
+ - Generated `tokens.json` is valid JSON with all token groups
146
+ - `rn-theme.ts` is only produced when `platform` includes `mobile` or `both`
147
+ - No hardcoded palette values exist in output (all derived from DESIGN.md)
148
+ - Every generated file carries the DO-NOT-EDIT header
149
+ - Output directory matches `theme_output` from front matter or defaults to `/mockups/.theme/`
package/AGENTS.md CHANGED
@@ -1,202 +1,108 @@
1
1
  # dev-tasks
2
2
 
3
- A set of agents, skills, and instructions for GitHub Copilot, Claude Code, Kiro, and other AI coding agents to run structured, PRD-driven development workflows.
3
+ Portable, repo-installed workflow harness for structured, PRD-driven AI-assisted development. Agents orchestrate the workflow end-to-end with branch discipline, test-first design, and GitHub-as-source-of-truth.
4
4
 
5
- ## Core Idea
5
+ ## Contracts
6
6
 
7
- This system brings structure and clarity to AI-assisted development by:
7
+ | File | Owner | Purpose |
8
+ | ------------- | ------------- | ---------------------------------------------- |
9
+ | `/DESIGN.md` | `ux-engineer` | Canonical design-system tokens and UI guidance |
10
+ | `/TESTING.md` | `qa-engineer` | Layer taxonomy, runners, thresholds, fixtures |
8
11
 
9
- - Defining scope with Product Requirements Documents (PRDs)
10
- - Breaking requirements into actionable, implementation-ready tasks
11
- - Guiding the AI to tackle one task at a time with checkpoints for review
12
- - Providing specialized **agents** that orchestrate the workflow end-to-end
13
- - Enforcing documentation, branch discipline, and GitHub-as-source-of-truth
14
- - Standardizing visual design decisions through `/DESIGN.md` as the canonical UI contract
15
- - **Test-first design as the default**: `verifier` (Design Mode) produces compliance test plans before implementation, and `developer` writes tests before code
12
+ If `/DESIGN.md` is missing and scope includes UI work, agents **MUST** create a baseline before finalizing design-dependent outputs. An unfilled `/TESTING.md` placeholder means "no standard established", never permission.
16
13
 
17
- ## Design Standard Contract (DESIGN.md)
14
+ ## Taxonomy
18
15
 
19
- `/DESIGN.md` is the canonical design-system artifact for this repository.
20
-
21
- - `ux-engineer` **MUST** use `/DESIGN.md` as the primary style source for mockups.
22
- - `product-engineer` **MUST** reference `/DESIGN.md` for UI-impacting specs and stories.
23
- - `developer` **MUST** validate UI changes against `/DESIGN.md` and update it when the visual contract changes.
24
- - `planner` **MUST** require DESIGN.md compliance in UI-impacting delegated runs.
25
-
26
- If `/DESIGN.md` is missing and the requested scope includes UI work, agents **MUST** create a baseline DESIGN.md before finalizing design-dependent outputs.
27
-
28
- ---
29
-
30
- ## Testing Standard Contract (TESTING.md)
31
-
32
- `/TESTING.md` is the canonical testing contract for a repository. It declares the layer taxonomy and what belongs at each layer, the per-package runner and commands, coverage thresholds and baseline policy, the fixture and mocking strategy, and the mandatory security-negative cases.
33
-
34
- - `qa-engineer` **OWNS** `/TESTING.md` and fills it per project via `activity-test-standards`.
35
- - `developer` **MUST** keep it current when the testing contract changes.
36
- - Agents that read it **MUST** treat an unfilled placeholder as "no standard established", never as permission.
37
- - The contract is **per-package**: a repository mixing languages (for example vitest and pytest) **MUST** be describable without forcing every package into one language's script names.
38
-
39
- It ships with dev-tasks as a placeholder and is listed in `consumer_owned_paths`, so `dev-tasks update` never overwrites a filled version.
40
-
41
- ---
42
-
43
- ## Taxonomy: Agent vs Skill vs Instruction
44
-
45
- | Concept | Purpose | Loaded When |
46
- | --------------- | ----------------------------------------------------------- | ---------------------------- |
47
- | **Agent** | Autonomous role with decision-making and handoff discipline | Invoked by name (`@agent`) |
48
- | **Skill** | Reusable on-demand capability (procedures/activities) | On demand (invoked by agent) |
49
- | **Instruction** | Scoped rule enforced automatically for matching context | Auto-applied by runtime |
50
-
51
- ---
16
+ | Concept | Purpose | Loaded When |
17
+ | --------------- | -------------------------------------------- | ----------------------- |
18
+ | **Agent** | Autonomous role with decisions and handoffs | Invoked by name |
19
+ | **Skill** | Reusable on-demand procedure | On demand by agent |
20
+ | **Instruction** | Scoped rule auto-applied to matching context | Auto-applied by runtime |
52
21
 
53
22
  ## Agents
54
23
 
55
- | Agent | File | Purpose |
56
- | -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
57
- | **product-engineer** | `product-engineer.agent.md` | Preparation agent — owns the full pre-coding chain: PRD, spec, stories, plan. Owns drift-reconciliation (`activity-drift-reconciliation`) for findings handed off by `developer`/`planner`. Hands off to `developer` or `planner` for execution. |
58
- | **developer** | `developer.agent.md` | Execution agent — implements code from an existing task list. Runs `implement`, including a mandatory, non-skippable `verifier` audit before every PR is marked ready. |
59
- | **planner** | `planner.agent.md` | Multi-story orchestration — dependency-ordered sequential execution with checkpoint/resume, a mandatory per-story and PRD-level rollup `verifier` audit gate, and one consolidated integration PR. |
60
- | **technical-writer** | `technical-writer.agent.md` | Autonomous documentation maintenance |
61
- | **housekeeping** | `housekeeping.agent.md` | Lint, type, and test-wiring fixes |
62
- | **github-ops** | `github-ops.agent.md` | GitHub consistency — standardizes issues, PRs, branches, labels, milestones, comments, and enforces merge authority policy |
63
- | **ux-engineer** | `ux-engineer.agent.md` | UX prototyping and gap analysis — turns PRD/SPEC into testable mockups and feeds refinements back to `product-engineer` |
64
- | **qa-engineer** | `qa-engineer.agent.md` | Quality agent — establishes the `/TESTING.md` standard, authors tests for layers the project lacks, and reports coverage and structural gaps. Invoked by `developer` at the completion gate, before the `verifier` audit |
65
- | **verifier** | `verifier.agent.md` | Verification agent — owns compliance test-plan design (`design` mode) and post-implementation grey-box fidelity auditing (`audit` mode) against codebase, `/workstream`, tests, and PRD/spec intent |
66
-
67
- `.github/agents/` and `.kiro/agents/` carry all nine agents. `.claude/agents/` carries seven by design: `planner` and `product-engineer` are orchestrators that must pause for user-approval gates, so on Claude Code they run in the main thread as `.claude/commands/` entry points rather than as subagents. See `CLAUDE.md`.
24
+ | Agent | Purpose |
25
+ | -------------------- | -------------------------------------------------------------------------------- |
26
+ | **product-engineer** | Preparation — PRD, spec, stories, plan. Owns drift-reconciliation. |
27
+ | **developer** | Execution — implements from task lists with mandatory verifier audit pre-PR. |
28
+ | **planner** | Multi-story orchestration with dependency ordering and integration PR. |
29
+ | **technical-writer** | Autonomous documentation maintenance. |
30
+ | **housekeeping** | Lint, type, and test-wiring fixes. |
31
+ | **github-ops** | GitHub consistency — issues, PRs, branches, labels, milestones, merge authority. |
32
+ | **ux-engineer** | UX prototyping, DESIGN.md ownership, mockup generation. |
33
+ | **qa-engineer** | Testing standard, test authoring, coverage/gap reporting. |
34
+ | **researcher** | Bounded codebase investigation producing structured research artifacts. |
35
+ | **verifier** | Compliance test-plan design and post-implementation fidelity audit. |
36
+
37
+ Platform coverage: `.github/agents/` and `.kiro/agents/` carry all ten. `.claude/agents/` carries eight — `planner` and `product-engineer` run as `.claude/commands/` (need user-approval gates).
68
38
 
69
39
  ## Skills
70
40
 
71
- Skills are on-demand capabilities invoked by agents — **not** loaded unless explicitly referenced.
72
-
73
41
  ### Activity Skills
74
42
 
75
- | Skill | Directory | Purpose | Primary Consumer |
76
- | ---------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
77
- | **activity-init** | `skills/activity-init/` | Establish product context and technical guidelines (mono/multi-repo/greenfield mode detection) | `product-engineer` |
78
- | **activity-refine** | `skills/activity-refine/` | Clarify scope — issue refinement or full PRD creation | `product-engineer` |
79
- | **activity-generate-spec** | `skills/activity-generate-spec/` | Transform PRD into technical specification | `product-engineer` |
80
- | **activity-generate-stories** | `skills/activity-generate-stories/` | Break spec into user stories with coverage validation | `product-engineer` |
81
- | **activity-publish-github** | `skills/activity-publish-github/` | Publish stories as GitHub Issues via MCP | `product-engineer` |
82
- | **activity-e2e-test-design** | `skills/activity-e2e-test-design/` | End-to-end black-box test scenario generation from spec/stories | `verifier` |
83
- | **activity-contract-test-design** | `skills/activity-contract-test-design/` | Consumer/provider contract and schema compatibility test strategy | `verifier` |
84
- | **activity-edge-case-refinement** | `skills/activity-edge-case-refinement/` | Systematic edge-case discovery by category with concrete examples | `verifier` |
85
- | **activity-random-test-tactics** | `skills/activity-random-test-tactics/` | Randomized, fuzz, and property-inspired test generation with reproducibility | `verifier` |
86
- | **activity-test-standards** | `skills/activity-test-standards/` | Establish and maintain `/TESTING.md`, detect harness defects, verify test-script and CI/deploy gate reachability | `qa-engineer` |
87
- | **activity-test-implementation** | `skills/activity-test-implementation/` | Author Layer 1-2 tests with enforceable boundaries and a mandatory security-negative category | `qa-engineer` |
88
- | **activity-coverage-gap-analysis** | `skills/activity-coverage-gap-analysis/` | Measure coverage against a baseline, or run risk-ranked structural gap analysis when no provider exists | `qa-engineer` |
89
- | **activity-drift-reconciliation** | `skills/activity-drift-reconciliation/` | Routes verifier drift findings into task-list/checklist expansion, new issues, or PRD/spec changelog write-back (human-confirmed) | `product-engineer` |
43
+ | Skill | Purpose | Consumer |
44
+ | ---------------------------------------- | --------------------------------------------------------- | ---------------- |
45
+ | activity-init | Establish product context and technical guidelines | product-engineer |
46
+ | activity-refine | Issue refinement or full PRD creation | product-engineer |
47
+ | activity-codebase-research | Bounded codebase investigation with structured artifact | researcher |
48
+ | activity-generate-spec | PRD to technical specification | product-engineer |
49
+ | activity-generate-stories | Spec to user stories with coverage validation | product-engineer |
50
+ | activity-publish-github | Publish stories as GitHub Issues | product-engineer |
51
+ | activity-e2e-test-design | E2E scenario generation from spec/stories | verifier |
52
+ | activity-contract-test-design | Contract and schema compatibility test strategy | verifier |
53
+ | activity-edge-case-refinement | Systematic edge-case discovery | verifier |
54
+ | activity-random-test-tactics | Randomized/fuzz/property test generation | verifier |
55
+ | activity-test-standards | Establish/maintain TESTING.md, detect harness defects | qa-engineer |
56
+ | activity-test-implementation | Author Layer 1-2 tests with security-negative category | qa-engineer |
57
+ | activity-integration-test-implementation | Layer 2.5 tests against real databases | qa-engineer |
58
+ | activity-e2e-test-implementation | Playwright E2E from verifier scenario tables | qa-engineer |
59
+ | activity-contract-validation | API contract drift/breaking-change detection | qa-engineer |
60
+ | activity-coverage-gap-analysis | Coverage measurement or structural gap analysis | qa-engineer |
61
+ | activity-drift-reconciliation | Route drift findings to task expansion or spec write-back | product-engineer |
90
62
 
91
63
  ### Operational Skills
92
64
 
93
- | Skill | Directory | Purpose | Primary Consumer |
94
- | ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
95
- | **git-ops** | `skills/git-ops/` | Branch management, rebase, merge, conflict resolution, recovery | `developer`, `planner` |
96
- | **webapp-mockup** | `skills/webapp-mockup/` | Scaffold and generate React mockup apps for UX testing | `ux-engineer` |
97
- | **memo-cli-usage** | `skills/memo-cli-usage/` | Read and write architectural decisions to a shared Qdrant knowledge base for multi-session, multi-agent, and team-wide context continuity | `technical-writer`, `developer` |
98
-
99
- ### Third-Party Skills
100
-
101
- None currently vendored. Third-party skills, when added, are installed under each platform's skills directory alongside the skills above.
65
+ | Skill | Purpose | Consumer |
66
+ | -------------- | ----------------------------------------------------- | --------------------------- |
67
+ | git-ops | Branch management, rebase, merge, conflict resolution | developer, planner |
68
+ | ux-scaffold | Mockup project creation (html-lite, react-full) | ux-engineer |
69
+ | ux-theme-gen | Generate theme artifacts from DESIGN.md | ux-engineer, developer |
70
+ | memo-cli-usage | Read/write decisions to shared knowledge base | technical-writer, developer |
102
71
 
103
- ## Instructions (Scoped)
72
+ ## Instructions
104
73
 
105
- Instructions are scoped via `applyTo`/`fileMatchPattern` and auto-applied to matching files. Claude Code has no scoped-instruction mechanism, so `plan` and `implement` ship there as skills instead.
106
-
107
- | Instruction | Copilot / Kiro file | Claude equivalent | Scope | Purpose |
108
- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
109
- | **plan** | `.github/instructions/plan.instructions.md` / `.kiro/steering/plan.md` | `.claude/skills/plan/` | `workstream/**` | Convert stories or refined issues into execution-ready task lists |
110
- | **implement** | `.github/instructions/implement.instructions.md` / `.kiro/steering/implement.md` | `.claude/skills/implement/` | `workstream/**/tasks-*.md` | Execute task list with step-gated approval, branching, and PR discipline |
111
- | **nextjs-pages-components** | `.github/instructions/domain/nextjs-pages-components.instructions.md` / `.kiro/steering/nextjs-pages-components.md` | — | `**/app/**/*.tsx` | Next.js + React conventions |
112
- | **git-guard-notice** | `.kiro/steering/git-guard-notice.md` | — | Always loaded (Kiro) | Restates the three git invariants: no push/merge to `main`, Conventional Commits, `--body-file` for `gh` bodies |
74
+ | Instruction | Scope | Purpose |
75
+ | ----------------------- | -------------------------- | -------------------------------------------------- |
76
+ | plan | `workstream/**` | Convert stories/issues into task lists |
77
+ | implement | `workstream/**/tasks-*.md` | Execute task list with branching and PR discipline |
78
+ | nextjs-pages-components | `**/app/**/*.tsx` | Next.js + React conventions |
79
+ | git-guard-notice | Always (Kiro) | Git invariants reminder |
113
80
 
114
81
  ## Hooks
115
82
 
116
- | Hook | Files | Purpose |
117
- | ---------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
118
- | **git-guard** | `.kiro/hooks/git-guard.json`, `.kiro/hooks/scripts/git-guard.sh`, `.claude/hooks/git-guard.sh` | Blocks pushes/merges to `main`, non-Conventional commit messages, and inline `gh --body` |
119
- | **branch-guard** | `.kiro/hooks/scripts/branch-guard.sh` | Blocks write operations while on the default branch |
120
-
121
- Hook enforcement is best-effort. Human PR review is the actual gate for these invariants.
122
-
123
- ## Prompts
83
+ | Hook | Purpose |
84
+ | ------------ | ---------------------------------------------------------------------------- |
85
+ | git-guard | Blocks pushes/merges to `main`, non-Conventional commits, inline `gh --body` |
86
+ | branch-guard | Blocks write operations on default branch |
124
87
 
125
- See individual agent files for invocation modes and entry points. Reference: Copilot (`.github/prompts/`), Claude Code (`.claude/commands/`), Kiro (embedded in `.kiro/agents/`).
126
-
127
- ---
128
-
129
- ## Agent File Format (Kiro Custom Agents)
130
-
131
- Agent files in `.kiro/agents/` use YAML frontmatter followed by a markdown body containing the system prompt. The frontmatter conforms to the [official Kiro custom agent configuration reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/).
132
-
133
- ### Frontmatter Schema
134
-
135
- ```yaml
136
- ---
137
- description: "<human-readable agent description>"
138
- tools: [<tool-tags>] # Allowed: read, write, shell, web
139
- resources: # Context files auto-loaded into the agent
140
- - file://<relative-path> # Project files (e.g., file://AGENTS.md)
141
- - skill://<glob-pattern> # Skill definitions (e.g., skill://.kiro/skills/**/SKILL.md)
142
- permissions: # (Optional) Fine-grained access control
143
- - allow: <action>
144
- paths: ["<glob>"]
145
- - deny: <action>
146
- paths: ["<glob>"]
147
- ---
148
- ```
149
-
150
- ### Field Reference
151
-
152
- | Field | Required | Description |
153
- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154
- | `description` | Yes | Human-readable purpose. Used by the runtime for agent selection and routing. |
155
- | `tools` | Yes | Tag-based tool categories: `read`, `write`, `shell`, `web`. Use `["*"]` for unrestricted. |
156
- | `resources` | No | Context files auto-loaded via `file://` (project files) and `skill://` (skill definitions). |
157
- | `permissions` | No | Inline permission rules for fine-grained access control (allow/deny by path glob). **Note:** Not yet supported by the Kiro runtime as of v1.0 — presence causes agents to fail to load. |
158
- | `model` | No | Model selection override (omit to use the runtime default). |
159
- | `mcpServers` | No | Embedded MCP server configurations for tool extensions. |
160
- | `allowedTools` | No | Tools that execute without prompting (pre-approved). |
161
-
162
- ### Tool Categories
163
-
164
- | Tag | Grants Access To |
165
- | ------- | ------------------------------------- |
166
- | `read` | File reading, search, code navigation |
167
- | `write` | File creation, editing, deletion |
168
- | `shell` | Terminal command execution |
169
- | `web` | Web browsing and HTTP requests |
170
-
171
- > **Note:** `subagent` is not an official tool category. Subagent delegation is a runtime capability, not a tool permission.
172
-
173
- ### References
174
-
175
- - [Kiro Custom Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/)
176
- - [Kiro CLI v3 Agent Config](https://kiro.dev/docs/cli/v3/agent-config/)
177
- - [Sample Multi-Agent Repository](https://github.com/aws-samples/sample-kiro-cli-multiagent-development)
178
-
179
- ---
88
+ Hook enforcement is best-effort. Human PR review is the actual gate.
180
89
 
181
90
  ## General Agent Guidelines
182
91
 
183
- All AI coding agents working in this repository **MUST**:
92
+ All agents **MUST**:
184
93
 
185
- - Always create feature branches — never commit to the default branch
94
+ - Create feature branches — never commit to default branch
186
95
  - Use Conventional Commits (`feat`, `fix`, `chore`, `docs`, etc.)
187
- - Create PRs for review — never self-merge into `main`
188
- - **PRs targeting `main` require user approval** — no agent may merge into the default branch
189
- - Follow testing, linting, and documentation standards from `technical-guidelines.md`
96
+ - Create PRs for review — never self-merge into `main`; PRs targeting `main` require user approval
97
+ - Follow standards from `technical-guidelines.md`
190
98
  - Reference GitHub Issues in branch names and commits
191
- - Treat `/DESIGN.md` as the source of truth for visual tokens, components, and design guidance
192
- - Prefer `pnpm` over `npm` for JS/TS workflows
193
- - Use canonical script names: `lint`, `format:check`, `typecheck`, `test`, `audit`, `validate`
194
- - Enforce quality gates before completion: `test`, `lint`, `format:check`, `typecheck`, `audit`
195
- - Use the `git-ops` skill for branch management, rebase, and conflict resolution
196
- - `qa-engineer` runs at the completion gate, before the `verifier` audit, and records `coverage_gate`. It **MAY** be skipped only as `SKIPPED(<reason>)` with a non-empty reason; omitting the field is treated as incomplete.
197
- - The `verifier` audit is mandatory and non-skippable before every PR is marked ready. Drift findings are non-blocking and route to `product-engineer`'s `activity-drift-reconciliation`.
198
- - **Test-first design is the default:** `product-engineer` recommends `verifier` Design Mode after planning; `developer` writes tests before implementation code; `planner` checks for test plans and enforces test-first in developer handoffs
199
- - If `memo-cli` is installed and configured: agents **MUST** read/write entries per their role (see agent files for details)
99
+ - Prefer `pnpm` over `npm`; use canonical scripts: `lint`, `format:check`, `typecheck`, `test`, `audit`, `validate`
100
+ - Enforce quality gates before completion
101
+ - Use `git-ops` for complex branch operations
102
+ - Run `qa-engineer` at completion gate (record `coverage_gate: PASS | FAIL | SKIPPED(<reason>)`)
103
+ - Run `verifier` audit (mandatory, non-skippable) before PR is ready; drift findings route to `product-engineer`
104
+ - Follow test-first design: write tests before implementation code
105
+ - If `memo-cli` is available: read/write entries per role
200
106
 
201
107
  ---
202
108
 
@@ -204,93 +110,64 @@ All AI coding agents working in this repository **MUST**:
204
110
 
205
111
  ### architecture-change
206
112
 
207
- The `architecture-change` task type is the **only** mode that grants write authority to the meta-repo (the shared architecture/catalog repository). It enforces structural integrity of the semantic layer by restricting what can be modified, requiring formal decision records, and mandating human approval.
113
+ The only mode granting write authority to the meta-repo. Agents **MUST NOT** write to the meta-repo outside this task type — applies to `product-engineer`, `developer`, `planner`, `housekeeping`, and all others.
208
114
 
209
115
  #### Write Scope (RF-62)
210
116
 
211
- An `architecture-change` task **MAY** modify:
212
-
213
- - `architecture.md`
214
- - `domains.md`
215
- - `glossary.md`
216
- - `conventions.md`
217
- - `catalog/flows/` (flow definitions)
218
-
219
- An `architecture-change` task **MUST NOT** modify:
117
+ **MAY** modify: `architecture.md`, `domains.md`, `glossary.md`, `conventions.md`, `catalog/flows/`.
220
118
 
221
- - `catalog/components/*.json` — generated by CI from component-repo extraction; never hand-edited or agent-edited
222
- - `catalog/index.yaml` — generated by `dt catalog build`; never hand-edited or agent-edited
119
+ **MUST NOT** modify: `catalog/components/*.json`, `catalog/index.yaml` — generated by CI (`dt extract` and `dt catalog build`), never hand-edited or agent-edited.
223
120
 
224
121
  #### Generated-File Prohibition
225
122
 
226
- `catalog/components/*.json` and `catalog/index.yaml` are **generated artifacts** produced by CI pipelines (`dt extract` and `dt catalog build`). No agent or human may edit these files directly. Changes to component metadata flow exclusively through the component-repo extraction pipeline.
123
+ `catalog/components/*.json` and `catalog/index.yaml` are generated by CI pipelines. No agent or human may edit these files directly.
227
124
 
228
125
  #### ADR Requirement
229
126
 
230
- Before opening any meta-repo PR under the `architecture-change` task type, the agent **MUST** produce an Architecture Decision Record (ADR) containing:
231
-
232
- - **Context:** Why the change is needed
233
- - **Decision:** What is being changed
234
- - **Consequences:** Impact on consumers, domains, or contracts
235
- - **Alternatives considered:** Other approaches evaluated and reasons for rejection
236
-
237
- The ADR **MUST** be committed as part of the PR (in the meta-repo's ADR directory).
127
+ Before opening any meta-repo PR under this task type, the agent **MUST** produce an Architecture Decision Record (ADR) containing: **Context** (why), **Decision** (what), **Consequences** (impact), and **Alternatives considered** (rejected approaches). The ADR **MUST** be committed as part of the PR.
238
128
 
239
129
  #### Human Approval Gate
240
130
 
241
- - PRs from the `architecture-change` task type targeting the meta-repo **REQUIRE** explicit human review and approval.
242
- - No agent may auto-merge an `architecture-change` PR into the default branch.
243
- - This aligns with the existing branch/PR discipline: PRs targeting `main` require user approval.
131
+ PRs from this task type targeting the meta-repo **REQUIRE** explicit human review and approval. No agent may auto-merge an `architecture-change` PR into the default branch.
244
132
 
245
133
  #### Exclusion Rule (RF-64)
246
134
 
247
- Agents **MUST NOT** write to the meta-repo outside the `architecture-change` task type. Any attempt to modify meta-repo files (including those in the allowed write scope) outside this task type **MUST** be refused with a clear message:
135
+ Agents **MUST NOT** write to the meta-repo outside the `architecture-change` task type. Refuse with:
248
136
 
249
137
  > "Meta-repo writes require the `architecture-change` task type. Create an architecture-change task to modify these files."
250
138
 
251
- This applies to all agents (`product-engineer`, `developer`, `planner`, `housekeeping`, etc.).
252
-
253
139
  ---
254
140
 
255
141
  ## Cross-Repo Partitioning (RF-63)
256
142
 
257
- When a scoping step (via `dt init --task` or manual multi-repo planning) identifies more than one `primary` component, the feature spans multiple repositories. In this case, the agent **MUST** partition the work into per-repo sub-tasks rather than treating it as a single monolithic task.
143
+ When a scoping step identifies more than one `primary` component, the feature spans multiple repositories and the agent **MUST** partition the work into per-repo sub-tasks.
258
144
 
259
145
  ### Partitioning Procedure
260
146
 
261
- 1. **Detection:** If `scope.primary` contains >1 component, the feature is cross-repo and **MUST** be partitioned.
147
+ 1. **Detection:** If `scope.primary` contains >1 component, partition is **REQUIRED**.
262
148
  2. **One sub-task per repo:** Each `primary` component becomes its own sub-task, scoped exclusively to that component's repository.
263
- 3. **Partition proposal consumption:** When a partition proposal is available from `dt scope gate` (G1 abort, exit 7), the agent **SHOULD** use it as the basis for the partition. When no automated proposal is available, the agent **MUST** apply the same rules manually.
149
+ 3. **Partition proposal:** When a partition proposal is available from `dt scope gate` (G1 abort, exit 7), the agent **SHOULD** use it as the basis for the partition. When no proposal exists, the agent **MUST** apply the same rules manually.
264
150
 
265
151
  ### Contract-as-Interface
266
152
 
267
- - Each sub-task uses the **boundary contract** (with a target version) as its interface.
268
- - Acceptance criteria for each sub-task **MUST** reference the contract definition (OpenAPI spec, AsyncAPI channel, or schema), **not** the foreign repo's internal implementation.
269
- - A sub-task is complete when it satisfies its contract obligations — it does not depend on or verify the other repo's implementation details.
153
+ Each sub-task uses the **boundary contract** (with a target version) as its interface. Acceptance criteria **MUST** reference the contract definition, **not** the foreign repo's internal implementation.
270
154
 
271
155
  ### Ordering Rule
272
156
 
273
- Sub-tasks **MUST** be ordered **producer-before-consumers**:
274
-
275
- - The provider (producer) implements its contract first.
276
- - Consumer sub-tasks implement adaptation to the contract after the provider sub-task is complete.
277
- - This ensures the contract exists in its target form before consumers adapt to it.
157
+ Sub-tasks **MUST** be ordered producer-before-consumers: the provider (producer) implements its contract first. Consumer sub-tasks implement adaptation to the contract after the provider sub-task is complete.
278
158
 
279
159
  ### Low-Payload Elevation Guard
280
160
 
281
- A boundary contract with `payload_confidence: low` **MUST** be raised to at least `medium` confidence before it can serve as an acceptance boundary. This is achieved by:
282
-
283
- - Re-running extraction (`dt extract`) with improved source hints, OR
284
- - Manual confirmation of the payload shape by a human reviewer.
161
+ A boundary contract with `payload_confidence: low` **MUST** be raised to at least `medium` before use as an acceptance boundary. This is achieved by Re-running extraction (`dt extract`) with improved source hints, or Manual confirmation of the payload shape by a human reviewer.
285
162
 
286
- Until the boundary contract reaches `medium` or higher confidence, the agent **MUST NOT** use it as an acceptance interface and **MUST** block the sub-task that depends on it with a clear message:
163
+ Until elevated, the agent **MUST NOT** use it as an acceptance interface and **MUST** block the sub-task with:
287
164
 
288
165
  > "Boundary contract `<contract-id>` has `payload_confidence: low`. Re-run extraction or manually confirm the payload shape before using it as an acceptance boundary."
289
166
 
290
167
  ### Single-Primary — No Partition
291
168
 
292
- When `scope.primary` contains exactly 1 component, no partitioning is needed. The feature is single-repo and proceeds with normal task planning.
169
+ When `scope.primary` contains exactly 1 component, no partitioning is needed. The feature is single-repo and proceeds normally.
293
170
 
294
171
  ---
295
172
 
296
- For workflow chains and sequencing diagrams, see [`docs/workflow-chains.md`](docs/workflow-chains.md). For architecture, artifacts, and invariants, see [`docs/system-overview.md`](docs/system-overview.md) and [`docs/data-model.md`](docs/data-model.md). Full documentation index: [`docs/README.md`](docs/README.md).
173
+ For workflow chains: [`docs/workflow-chains.md`](docs/workflow-chains.md). For architecture and invariants: [`docs/system-overview.md`](docs/system-overview.md). Full docs index: [`docs/README.md`](docs/README.md).