@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.
- package/.claude/agents/developer.md +11 -0
- package/.claude/agents/qa-engineer.md +31 -2
- package/.claude/agents/researcher.md +96 -0
- package/.claude/agents/ux-engineer.md +118 -114
- package/.claude/commands/planner.md +22 -7
- package/.claude/commands/product-engineer.md +37 -10
- package/.claude/commands/researcher.md +28 -0
- package/.claude/skills/activity-codebase-research/SKILL.md +158 -0
- package/.claude/skills/activity-contract-validation/SKILL.md +167 -0
- package/.claude/skills/activity-e2e-test-implementation/SKILL.md +156 -0
- package/.claude/skills/activity-integration-test-implementation/SKILL.md +156 -0
- package/.claude/skills/activity-refine/SKILL.md +1 -0
- package/.claude/skills/activity-test-standards/SKILL.md +41 -0
- package/.claude/skills/ux-scaffold/SKILL.md +129 -0
- package/.claude/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
- package/.claude/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
- package/.claude/skills/ux-theme-gen/SKILL.md +149 -0
- package/.github/agents/developer.agent.md +11 -0
- package/.github/agents/planner.agent.md +22 -7
- package/.github/agents/product-engineer.agent.md +37 -10
- package/.github/agents/qa-engineer.agent.md +30 -3
- package/.github/agents/researcher.agent.md +96 -0
- package/.github/agents/ux-engineer.agent.md +119 -114
- package/.github/prompts/researcher.prompt.md +29 -0
- package/.github/skills/activity-codebase-research/SKILL.md +158 -0
- package/.github/skills/activity-contract-validation/SKILL.md +167 -0
- package/.github/skills/activity-e2e-test-implementation/SKILL.md +156 -0
- package/.github/skills/activity-integration-test-implementation/SKILL.md +156 -0
- package/.github/skills/activity-refine/SKILL.md +6 -0
- package/.github/skills/activity-test-standards/SKILL.md +41 -0
- package/.github/skills/ux-scaffold/SKILL.md +129 -0
- package/.github/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
- package/.github/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
- package/.github/skills/ux-theme-gen/SKILL.md +149 -0
- package/.kiro/agents/developer.md +11 -0
- package/.kiro/agents/planner.md +22 -7
- package/.kiro/agents/product-engineer.md +37 -10
- package/.kiro/agents/qa-engineer.md +30 -3
- package/.kiro/agents/researcher.md +99 -0
- package/.kiro/agents/ux-engineer.md +119 -132
- package/.kiro/agents/verifier.md +1 -1
- package/.kiro/skills/activity-codebase-research/SKILL.md +158 -0
- package/.kiro/skills/activity-contract-validation/SKILL.md +167 -0
- package/.kiro/skills/activity-e2e-test-implementation/SKILL.md +156 -0
- package/.kiro/skills/activity-integration-test-implementation/SKILL.md +156 -0
- package/.kiro/skills/activity-refine/SKILL.md +1 -0
- package/.kiro/skills/activity-test-standards/SKILL.md +41 -0
- package/.kiro/skills/ux-scaffold/SKILL.md +129 -0
- package/.kiro/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
- package/.kiro/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
- package/.kiro/skills/ux-theme-gen/SKILL.md +149 -0
- package/AGENTS.md +91 -214
- package/CHANGELOG.md +64 -0
- package/CLAUDE.md +3 -2
- package/DESIGN.md +233 -0
- package/README.md +31 -28
- package/TESTING.md +19 -11
- package/bundle-manifest.json +1 -0
- package/dist/core/distribution/doctor.d.ts +2 -2
- package/dist/core/distribution/doctor.js +3 -3
- package/dist/core/distribution/profiles.d.ts.map +1 -1
- package/dist/core/distribution/profiles.js +1 -1
- package/dist/core/distribution/profiles.js.map +1 -1
- package/package.json +4 -3
- package/.claude/skills/webapp-mockup/SKILL.md +0 -76
- package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
- package/.github/skills/webapp-mockup/SKILL.md +0 -71
- package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
- 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
|
-
|
|
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
|
-
##
|
|
5
|
+
## Contracts
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
14
|
+
## Taxonomy
|
|
18
15
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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 |
|
|
56
|
-
| -------------------- |
|
|
57
|
-
| **product-engineer** |
|
|
58
|
-
| **developer** |
|
|
59
|
-
| **planner** |
|
|
60
|
-
| **technical-writer** |
|
|
61
|
-
| **housekeeping** |
|
|
62
|
-
| **github-ops** |
|
|
63
|
-
| **ux-engineer** |
|
|
64
|
-
| **qa-engineer** |
|
|
65
|
-
| **
|
|
66
|
-
|
|
67
|
-
|
|
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
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
|
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
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
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
|
|
72
|
+
## Instructions
|
|
104
73
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
|
108
|
-
|
|
|
109
|
-
|
|
|
110
|
-
|
|
|
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
|
|
117
|
-
|
|
|
118
|
-
|
|
|
119
|
-
|
|
|
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
|
-
|
|
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
|
|
92
|
+
All agents **MUST**:
|
|
184
93
|
|
|
185
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
192
|
-
-
|
|
193
|
-
- Use
|
|
194
|
-
-
|
|
195
|
-
-
|
|
196
|
-
-
|
|
197
|
-
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
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
|
|
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).
|