@llipe.com/dev-tasks 0.10.0 → 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/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-test-standards/SKILL.md +41 -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/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-test-standards/SKILL.md +41 -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/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-test-standards/SKILL.md +41 -0
- package/AGENTS.md +91 -215
- package/CHANGELOG.md +33 -0
- package/CLAUDE.md +3 -2
- package/README.md +1 -0
- package/TESTING.md +19 -11
- package/package.json +1 -1
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: activity-integration-test-implementation
|
|
3
|
+
description: "Author integration tests (Layer 2.5) against real databases — local via testcontainers/docker-compose/Supabase CLI, remote via testing environments. Covers migrations, RLS, pgTAP, fixtures, and fallback paths. Use when writing or backfilling integration tests."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Activity: Integration Test Implementation (Layer 2.5)
|
|
7
|
+
|
|
8
|
+
Author integration tests that exercise code against a real database. Layer 2.5 exists because mocking the data layer makes SQL errors, type mismatches, NULL handling, malformed joins, and RLS policies structurally invisible.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
> **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
|
|
13
|
+
|
|
14
|
+
## Goal
|
|
15
|
+
|
|
16
|
+
Produce integration tests that fail when the data layer is wrong. If the database is mocked, the test belongs at Layer 2, not here.
|
|
17
|
+
|
|
18
|
+
Consult `/TESTING.md` first. Its Layer 2.5 boundary governs; this skill supplies the method.
|
|
19
|
+
|
|
20
|
+
## Layer 2.5 Boundary
|
|
21
|
+
|
|
22
|
+
- **MUST** use a real database (Postgres, SQLite, etc.) — not a mock or in-memory fake.
|
|
23
|
+
- **MUST NOT** mock the data layer. If you mock `sql`, `prisma`, `drizzle`, or the ORM client, the test is Layer 2.
|
|
24
|
+
- **MUST NOT** assert on SQL text or internal query shape. Assert on persisted state or returned data.
|
|
25
|
+
- **MAY** mock third-party external services (payment gateways, email providers) at the HTTP boundary.
|
|
26
|
+
|
|
27
|
+
## Part 1 — Local Integration Environment Detection
|
|
28
|
+
|
|
29
|
+
Detect the easiest applicable local option. Prefer in this order:
|
|
30
|
+
|
|
31
|
+
### 1. Testcontainers (preferred for isolation)
|
|
32
|
+
|
|
33
|
+
- Look for `@testcontainers/postgresql` or equivalent in `package.json`/`pom.xml`/`Cargo.toml`.
|
|
34
|
+
- Requires Docker. Check: `docker info` succeeds.
|
|
35
|
+
- Each test suite gets an ephemeral container — full isolation, no cleanup conflicts.
|
|
36
|
+
|
|
37
|
+
### 2. Docker Compose
|
|
38
|
+
|
|
39
|
+
- Look for `docker-compose.yml` or `compose.yml` with a database service.
|
|
40
|
+
- Requires Docker. Shared instance across tests — needs explicit state reset.
|
|
41
|
+
|
|
42
|
+
### 3. Supabase Local CLI
|
|
43
|
+
|
|
44
|
+
- Look for `supabase/config.toml` or `.supabase/` directory.
|
|
45
|
+
- Check: `supabase status` succeeds.
|
|
46
|
+
- Provides real Postgres with auth, storage, and edge functions locally.
|
|
47
|
+
|
|
48
|
+
### 4. Fallback — No Local Environment
|
|
49
|
+
|
|
50
|
+
- If Docker is unavailable and Supabase CLI is not installed, report the limitation.
|
|
51
|
+
- Emit: `SKIPPED(no local database environment — Docker unavailable, Supabase CLI not installed)`.
|
|
52
|
+
- Recommend environment setup as a follow-up. Do not silently omit.
|
|
53
|
+
|
|
54
|
+
## Part 2 — Fixtures, Seeding, and Lifecycle
|
|
55
|
+
|
|
56
|
+
### Test isolation
|
|
57
|
+
|
|
58
|
+
- Each test **SHOULD** run in a transaction that rolls back on completion (preferred).
|
|
59
|
+
- Alternative: truncate affected tables in `beforeEach`/`afterEach`.
|
|
60
|
+
- Alternative for testcontainers: fresh container per suite (slower but fully isolated).
|
|
61
|
+
|
|
62
|
+
### Seeding
|
|
63
|
+
|
|
64
|
+
- Shared seed data lives in one location per package (e.g., `test/fixtures/seed.sql` or `test/helpers/seed.ts`).
|
|
65
|
+
- Seeds **MUST** be idempotent — running twice produces the same state.
|
|
66
|
+
- Seeds **MUST NOT** depend on auto-increment IDs. Use deterministic UUIDs or named references.
|
|
67
|
+
|
|
68
|
+
### Deterministic teardown
|
|
69
|
+
|
|
70
|
+
- Every integration test file **MUST** clean up after itself or use rollback isolation.
|
|
71
|
+
- Tests **MUST NOT** depend on execution order.
|
|
72
|
+
- Tests **MUST NOT** leave residual data that affects other test files.
|
|
73
|
+
|
|
74
|
+
## Part 3 — Migration Clean-Apply Tests
|
|
75
|
+
|
|
76
|
+
- **MUST** test that all migrations apply cleanly from an empty database.
|
|
77
|
+
- **MUST** verify apply order (no duplicate prefixes, no gaps).
|
|
78
|
+
- **MUST** verify idempotency: running migrations twice does not error.
|
|
79
|
+
- For large stacks (50+ migrations): run full clean-apply on CI/scheduled; run latest N on PR.
|
|
80
|
+
- Report duplicate migration prefixes as a finding.
|
|
81
|
+
|
|
82
|
+
## Part 4 — Row-Level Security (RLS) Policy Tests
|
|
83
|
+
|
|
84
|
+
RLS tests **MUST** exercise the real database policy, not application-level tenant checks in JavaScript.
|
|
85
|
+
|
|
86
|
+
### Multi-session setup
|
|
87
|
+
|
|
88
|
+
- Create at least two database roles or authenticated sessions (Tenant A, Tenant B).
|
|
89
|
+
- Use `SET ROLE` or separate connections per tenant.
|
|
90
|
+
- For Supabase: use `supabase.auth.admin.createUser()` for test users, then authenticate with their JWTs.
|
|
91
|
+
|
|
92
|
+
### Required assertions
|
|
93
|
+
|
|
94
|
+
| Case | Assertion |
|
|
95
|
+
| ---------------------------- | ----------------------------------- |
|
|
96
|
+
| Tenant A reads own data | Returns expected rows |
|
|
97
|
+
| Tenant A reads Tenant B data | Returns empty set or error |
|
|
98
|
+
| Tenant A writes to Tenant B | Insert/update fails or is invisible |
|
|
99
|
+
| Unauthenticated access | Denied by policy |
|
|
100
|
+
| Service role bypasses RLS | Returns all rows (when expected) |
|
|
101
|
+
|
|
102
|
+
### Record limitations
|
|
103
|
+
|
|
104
|
+
If isolation is asserted against application-level checks rather than the real RLS policy, you **MUST** record: "Production RLS policy unverified — tested against application-layer tenant filtering only."
|
|
105
|
+
|
|
106
|
+
## Part 5 — pgTAP / Schema Contract Tests
|
|
107
|
+
|
|
108
|
+
Use pgTAP (or equivalent: `pg_prove`, raw SQL assertions) for:
|
|
109
|
+
|
|
110
|
+
- Table and column existence.
|
|
111
|
+
- Constraint verification (NOT NULL, UNIQUE, CHECK, FK).
|
|
112
|
+
- Function and trigger existence and signatures.
|
|
113
|
+
- Permission grants per role.
|
|
114
|
+
- Index existence for query-critical paths.
|
|
115
|
+
|
|
116
|
+
When pgTAP is unavailable, use raw `SELECT` assertions against `information_schema` or `pg_catalog`.
|
|
117
|
+
|
|
118
|
+
## Part 6 — Remote Integration Testing
|
|
119
|
+
|
|
120
|
+
### Default: read-only
|
|
121
|
+
|
|
122
|
+
- Inspect schema, permissions, RLS policies, and data shape without mutation.
|
|
123
|
+
- Use `EXPLAIN` for query plan verification without executing writes.
|
|
124
|
+
- No approval required for read-only operations.
|
|
125
|
+
|
|
126
|
+
### Testing environment writes
|
|
127
|
+
|
|
128
|
+
- **REQUIRE** explicit user approval before any write or migration apply.
|
|
129
|
+
- Connect only to a dedicated testing environment — never to production for writes.
|
|
130
|
+
- After writes: verify applied state, then clean up test data.
|
|
131
|
+
- Record: environment name, operation performed, approval evidence.
|
|
132
|
+
|
|
133
|
+
### No testing environment available
|
|
134
|
+
|
|
135
|
+
- Report: "Remote integration limited to read-only inspection. No testing environment configured."
|
|
136
|
+
- Recommend environment setup. Do not fabricate a pass.
|
|
137
|
+
|
|
138
|
+
## Output
|
|
139
|
+
|
|
140
|
+
- Tests written or updated, by path and layer
|
|
141
|
+
- Local environment detection result (which option selected, or fallback triggered)
|
|
142
|
+
- Migration clean-apply result
|
|
143
|
+
- RLS policy test coverage per table with RLS enabled
|
|
144
|
+
- Schema contract coverage (tables, constraints, functions)
|
|
145
|
+
- Remote integration status (read-only / testing-env / unavailable)
|
|
146
|
+
- Stated limitations where real-policy testing was not possible
|
|
147
|
+
|
|
148
|
+
## Final Instructions
|
|
149
|
+
|
|
150
|
+
1. You **MUST** consult `/TESTING.md` and respect its Layer 2.5 boundary.
|
|
151
|
+
2. You **MUST NOT** mock the data layer. If the database is mocked, the test is Layer 2.
|
|
152
|
+
3. You **MUST** detect the local environment and recommend the easiest applicable option.
|
|
153
|
+
4. You **MUST** report a limitation when no local or remote environment is available.
|
|
154
|
+
5. You **MUST** test RLS against the real policy layer, not application-level checks.
|
|
155
|
+
6. You **MUST** require explicit approval before any remote write operation.
|
|
156
|
+
7. You **MUST NOT** install dependencies — detect and recommend only.
|
|
@@ -92,6 +92,47 @@ A monorepo defines `test:node` as `app && scraper && db` while the `api` package
|
|
|
92
92
|
|
|
93
93
|
Correct output: **defect** — `api` is unreachable from the aggregate; the CI gate and the deploy gate both let untested backend code through. Reporting "all script names conform" here is a false pass.
|
|
94
94
|
|
|
95
|
+
## Part 4 — Integration, E2E, and Contract Infrastructure Detection
|
|
96
|
+
|
|
97
|
+
Detect the presence and configuration state of higher-layer test infrastructure. Report findings as **informational** — missing infrastructure is not a defect, but it informs the gap analysis.
|
|
98
|
+
|
|
99
|
+
### Integration testing infrastructure
|
|
100
|
+
|
|
101
|
+
| Check | What to look for |
|
|
102
|
+
| ----------------------- | ------------------------------------------------------------- |
|
|
103
|
+
| **Testcontainers** | `@testcontainers/postgresql` or similar in dependencies |
|
|
104
|
+
| **Docker Compose** | `docker-compose.yml` or `compose.yml` with a database service |
|
|
105
|
+
| **Supabase local CLI** | `supabase/config.toml` or `.supabase/` directory |
|
|
106
|
+
| **Docker availability** | `docker info` succeeds (report if unavailable) |
|
|
107
|
+
|
|
108
|
+
### E2E testing infrastructure
|
|
109
|
+
|
|
110
|
+
| Check | What to look for |
|
|
111
|
+
| ------------------------- | -------------------------------------------------------------------------------- |
|
|
112
|
+
| **Playwright config** | `playwright.config.ts` or `playwright.config.js` present |
|
|
113
|
+
| **Base URL configured** | Config references `process.env.BASE_URL` or equivalent (not hardcoded localhost) |
|
|
114
|
+
| **Auth setup project** | A `global-setup` or setup project defined in Playwright config |
|
|
115
|
+
| **Browser install in CI** | CI workflow includes `playwright install` step |
|
|
116
|
+
| **`test:e2e` script** | Present in `package.json` and reachable from aggregate |
|
|
117
|
+
|
|
118
|
+
### Contract validation infrastructure
|
|
119
|
+
|
|
120
|
+
| Check | What to look for |
|
|
121
|
+
| -------------------------- | ------------------------------------------------------ |
|
|
122
|
+
| **OpenAPI spec** | `openapi.yaml`, `openapi.json`, `swagger.*` in repo |
|
|
123
|
+
| **AsyncAPI spec** | `asyncapi.yaml`, `asyncapi.json` in repo |
|
|
124
|
+
| **`dt` CLI** | `which dt` succeeds |
|
|
125
|
+
| **`test:contract` script** | Present in `package.json` and reachable from aggregate |
|
|
126
|
+
|
|
127
|
+
### Reporting
|
|
128
|
+
|
|
129
|
+
Report each finding as:
|
|
130
|
+
|
|
131
|
+
- `[INFO] <infrastructure> detected: <path or status>`
|
|
132
|
+
- `[INFO] <infrastructure> not found — Layer {X} tests require this`
|
|
133
|
+
|
|
134
|
+
These are informational findings for the gap analysis. They do **NOT** block or fail the standards check.
|
|
135
|
+
|
|
95
136
|
## Failure Modes
|
|
96
137
|
|
|
97
138
|
| Condition | Required behavior |
|
package/AGENTS.md
CHANGED
|
@@ -1,203 +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
|
-
|
|
100
|
-
### Third-Party Skills
|
|
101
|
-
|
|
102
|
-
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 |
|
|
103
71
|
|
|
104
|
-
## Instructions
|
|
72
|
+
## Instructions
|
|
105
73
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
| **nextjs-pages-components** | `.github/instructions/domain/nextjs-pages-components.instructions.md` / `.kiro/steering/nextjs-pages-components.md` | — | `**/app/**/*.tsx` | Next.js + React conventions |
|
|
113
|
-
| **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 |
|
|
114
80
|
|
|
115
81
|
## Hooks
|
|
116
82
|
|
|
117
|
-
| Hook
|
|
118
|
-
|
|
|
119
|
-
|
|
|
120
|
-
|
|
|
121
|
-
|
|
122
|
-
Hook enforcement is best-effort. Human PR review is the actual gate for these invariants.
|
|
123
|
-
|
|
124
|
-
## 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 |
|
|
125
87
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
130
|
-
## Agent File Format (Kiro Custom Agents)
|
|
131
|
-
|
|
132
|
-
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/).
|
|
133
|
-
|
|
134
|
-
### Frontmatter Schema
|
|
135
|
-
|
|
136
|
-
```yaml
|
|
137
|
-
---
|
|
138
|
-
description: "<human-readable agent description>"
|
|
139
|
-
tools: [<tool-tags>] # Allowed: read, write, shell, web
|
|
140
|
-
resources: # Context files auto-loaded into the agent
|
|
141
|
-
- file://<relative-path> # Project files (e.g., file://AGENTS.md)
|
|
142
|
-
- skill://<glob-pattern> # Skill definitions (e.g., skill://.kiro/skills/**/SKILL.md)
|
|
143
|
-
permissions: # (Optional) Fine-grained access control
|
|
144
|
-
- allow: <action>
|
|
145
|
-
paths: ["<glob>"]
|
|
146
|
-
- deny: <action>
|
|
147
|
-
paths: ["<glob>"]
|
|
148
|
-
---
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
### Field Reference
|
|
152
|
-
|
|
153
|
-
| Field | Required | Description |
|
|
154
|
-
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
155
|
-
| `description` | Yes | Human-readable purpose. Used by the runtime for agent selection and routing. |
|
|
156
|
-
| `tools` | Yes | Tag-based tool categories: `read`, `write`, `shell`, `web`. Use `["*"]` for unrestricted. |
|
|
157
|
-
| `resources` | No | Context files auto-loaded via `file://` (project files) and `skill://` (skill definitions). |
|
|
158
|
-
| `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. |
|
|
159
|
-
| `model` | No | Model selection override (omit to use the runtime default). |
|
|
160
|
-
| `mcpServers` | No | Embedded MCP server configurations for tool extensions. |
|
|
161
|
-
| `allowedTools` | No | Tools that execute without prompting (pre-approved). |
|
|
162
|
-
|
|
163
|
-
### Tool Categories
|
|
164
|
-
|
|
165
|
-
| Tag | Grants Access To |
|
|
166
|
-
| ------- | ------------------------------------- |
|
|
167
|
-
| `read` | File reading, search, code navigation |
|
|
168
|
-
| `write` | File creation, editing, deletion |
|
|
169
|
-
| `shell` | Terminal command execution |
|
|
170
|
-
| `web` | Web browsing and HTTP requests |
|
|
171
|
-
|
|
172
|
-
> **Note:** `subagent` is not an official tool category. Subagent delegation is a runtime capability, not a tool permission.
|
|
173
|
-
|
|
174
|
-
### References
|
|
175
|
-
|
|
176
|
-
- [Kiro Custom Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference/)
|
|
177
|
-
- [Kiro CLI v3 Agent Config](https://kiro.dev/docs/cli/v3/agent-config/)
|
|
178
|
-
- [Sample Multi-Agent Repository](https://github.com/aws-samples/sample-kiro-cli-multiagent-development)
|
|
179
|
-
|
|
180
|
-
---
|
|
88
|
+
Hook enforcement is best-effort. Human PR review is the actual gate.
|
|
181
89
|
|
|
182
90
|
## General Agent Guidelines
|
|
183
91
|
|
|
184
|
-
All
|
|
92
|
+
All agents **MUST**:
|
|
185
93
|
|
|
186
|
-
-
|
|
94
|
+
- Create feature branches — never commit to default branch
|
|
187
95
|
- Use Conventional Commits (`feat`, `fix`, `chore`, `docs`, etc.)
|
|
188
|
-
- Create PRs for review — never self-merge into `main`
|
|
189
|
-
-
|
|
190
|
-
- 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`
|
|
191
98
|
- Reference GitHub Issues in branch names and commits
|
|
192
|
-
-
|
|
193
|
-
-
|
|
194
|
-
- Use
|
|
195
|
-
-
|
|
196
|
-
-
|
|
197
|
-
-
|
|
198
|
-
-
|
|
199
|
-
- **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
|
|
200
|
-
- 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
|
|
201
106
|
|
|
202
107
|
---
|
|
203
108
|
|
|
@@ -205,93 +110,64 @@ All AI coding agents working in this repository **MUST**:
|
|
|
205
110
|
|
|
206
111
|
### architecture-change
|
|
207
112
|
|
|
208
|
-
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.
|
|
209
114
|
|
|
210
115
|
#### Write Scope (RF-62)
|
|
211
116
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
- `architecture.md`
|
|
215
|
-
- `domains.md`
|
|
216
|
-
- `glossary.md`
|
|
217
|
-
- `conventions.md`
|
|
218
|
-
- `catalog/flows/` (flow definitions)
|
|
219
|
-
|
|
220
|
-
An `architecture-change` task **MUST NOT** modify:
|
|
117
|
+
**MAY** modify: `architecture.md`, `domains.md`, `glossary.md`, `conventions.md`, `catalog/flows/`.
|
|
221
118
|
|
|
222
|
-
|
|
223
|
-
- `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.
|
|
224
120
|
|
|
225
121
|
#### Generated-File Prohibition
|
|
226
122
|
|
|
227
|
-
`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.
|
|
228
124
|
|
|
229
125
|
#### ADR Requirement
|
|
230
126
|
|
|
231
|
-
Before opening any meta-repo PR under
|
|
232
|
-
|
|
233
|
-
- **Context:** Why the change is needed
|
|
234
|
-
- **Decision:** What is being changed
|
|
235
|
-
- **Consequences:** Impact on consumers, domains, or contracts
|
|
236
|
-
- **Alternatives considered:** Other approaches evaluated and reasons for rejection
|
|
237
|
-
|
|
238
|
-
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.
|
|
239
128
|
|
|
240
129
|
#### Human Approval Gate
|
|
241
130
|
|
|
242
|
-
|
|
243
|
-
- No agent may auto-merge an `architecture-change` PR into the default branch.
|
|
244
|
-
- 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.
|
|
245
132
|
|
|
246
133
|
#### Exclusion Rule (RF-64)
|
|
247
134
|
|
|
248
|
-
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:
|
|
249
136
|
|
|
250
137
|
> "Meta-repo writes require the `architecture-change` task type. Create an architecture-change task to modify these files."
|
|
251
138
|
|
|
252
|
-
This applies to all agents (`product-engineer`, `developer`, `planner`, `housekeeping`, etc.).
|
|
253
|
-
|
|
254
139
|
---
|
|
255
140
|
|
|
256
141
|
## Cross-Repo Partitioning (RF-63)
|
|
257
142
|
|
|
258
|
-
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.
|
|
259
144
|
|
|
260
145
|
### Partitioning Procedure
|
|
261
146
|
|
|
262
|
-
1. **Detection:** If `scope.primary` contains >1 component,
|
|
147
|
+
1. **Detection:** If `scope.primary` contains >1 component, partition is **REQUIRED**.
|
|
263
148
|
2. **One sub-task per repo:** Each `primary` component becomes its own sub-task, scoped exclusively to that component's repository.
|
|
264
|
-
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.
|
|
265
150
|
|
|
266
151
|
### Contract-as-Interface
|
|
267
152
|
|
|
268
|
-
|
|
269
|
-
- Acceptance criteria for each sub-task **MUST** reference the contract definition (OpenAPI spec, AsyncAPI channel, or schema), **not** the foreign repo's internal implementation.
|
|
270
|
-
- 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.
|
|
271
154
|
|
|
272
155
|
### Ordering Rule
|
|
273
156
|
|
|
274
|
-
Sub-tasks **MUST** be ordered
|
|
275
|
-
|
|
276
|
-
- The provider (producer) implements its contract first.
|
|
277
|
-
- Consumer sub-tasks implement adaptation to the contract after the provider sub-task is complete.
|
|
278
|
-
- 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.
|
|
279
158
|
|
|
280
159
|
### Low-Payload Elevation Guard
|
|
281
160
|
|
|
282
|
-
A boundary contract with `payload_confidence: low` **MUST** be raised to at least `medium`
|
|
283
|
-
|
|
284
|
-
- Re-running extraction (`dt extract`) with improved source hints, OR
|
|
285
|
-
- 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.
|
|
286
162
|
|
|
287
|
-
Until
|
|
163
|
+
Until elevated, the agent **MUST NOT** use it as an acceptance interface and **MUST** block the sub-task with:
|
|
288
164
|
|
|
289
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."
|
|
290
166
|
|
|
291
167
|
### Single-Primary — No Partition
|
|
292
168
|
|
|
293
|
-
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.
|
|
294
170
|
|
|
295
171
|
---
|
|
296
172
|
|
|
297
|
-
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).
|