@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.
Files changed (39) 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/commands/planner.md +22 -7
  5. package/.claude/commands/product-engineer.md +37 -10
  6. package/.claude/commands/researcher.md +28 -0
  7. package/.claude/skills/activity-codebase-research/SKILL.md +158 -0
  8. package/.claude/skills/activity-contract-validation/SKILL.md +167 -0
  9. package/.claude/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  10. package/.claude/skills/activity-integration-test-implementation/SKILL.md +156 -0
  11. package/.claude/skills/activity-test-standards/SKILL.md +41 -0
  12. package/.github/agents/developer.agent.md +11 -0
  13. package/.github/agents/planner.agent.md +22 -7
  14. package/.github/agents/product-engineer.agent.md +37 -10
  15. package/.github/agents/qa-engineer.agent.md +30 -3
  16. package/.github/agents/researcher.agent.md +96 -0
  17. package/.github/prompts/researcher.prompt.md +29 -0
  18. package/.github/skills/activity-codebase-research/SKILL.md +158 -0
  19. package/.github/skills/activity-contract-validation/SKILL.md +167 -0
  20. package/.github/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  21. package/.github/skills/activity-integration-test-implementation/SKILL.md +156 -0
  22. package/.github/skills/activity-test-standards/SKILL.md +41 -0
  23. package/.kiro/agents/developer.md +11 -0
  24. package/.kiro/agents/planner.md +22 -7
  25. package/.kiro/agents/product-engineer.md +37 -10
  26. package/.kiro/agents/qa-engineer.md +30 -3
  27. package/.kiro/agents/researcher.md +99 -0
  28. package/.kiro/agents/verifier.md +1 -1
  29. package/.kiro/skills/activity-codebase-research/SKILL.md +158 -0
  30. package/.kiro/skills/activity-contract-validation/SKILL.md +167 -0
  31. package/.kiro/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  32. package/.kiro/skills/activity-integration-test-implementation/SKILL.md +156 -0
  33. package/.kiro/skills/activity-test-standards/SKILL.md +41 -0
  34. package/AGENTS.md +91 -215
  35. package/CHANGELOG.md +33 -0
  36. package/CLAUDE.md +3 -2
  37. package/README.md +1 -0
  38. package/TESTING.md +19 -11
  39. 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
- 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` **OWNS** `/DESIGN.md` and fills it per project via the interview-driven filling procedure. It **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, DESIGN.md ownership, and gap analysis — owns `/DESIGN.md`, generates navigable screen sets at two fidelity levels (html-lite, react-full), 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
- | **ux-scaffold** | `skills/ux-scaffold/` | Template-aware mockup project creation with DESIGN.md-derived tokens. Supports html-lite (zero-install, navigable) and react-full (shadcn + Vite + Radix) | `ux-engineer` |
97
- | **ux-theme-gen** | `skills/ux-theme-gen/` | Generate platform-specific theme artifacts from DESIGN.md. Use when mockups or production code need consumable tokens derived from the canonical design contract | `ux-engineer`, `developer` |
98
- | **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` |
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 (Scoped)
72
+ ## Instructions
105
73
 
106
- 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.
107
-
108
- | Instruction | Copilot / Kiro file | Claude equivalent | Scope | Purpose |
109
- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
110
- | **plan** | `.github/instructions/plan.instructions.md` / `.kiro/steering/plan.md` | `.claude/skills/plan/` | `workstream/**` | Convert stories or refined issues into execution-ready task lists |
111
- | **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 |
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 | Files | Purpose |
118
- | ---------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
119
- | **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` |
120
- | **branch-guard** | `.kiro/hooks/scripts/branch-guard.sh` | Blocks write operations while on the default branch |
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
- See individual agent files for invocation modes and entry points. Reference: Copilot (`.github/prompts/`), Claude Code (`.claude/commands/`), Kiro (embedded in `.kiro/agents/`).
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 AI coding agents working in this repository **MUST**:
92
+ All agents **MUST**:
185
93
 
186
- - Always create feature branches — never commit to the default branch
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
- - **PRs targeting `main` require user approval** — no agent may merge into the default branch
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
- - Treat `/DESIGN.md` as the source of truth for visual tokens, components, and design guidance
193
- - Prefer `pnpm` over `npm` for JS/TS workflows
194
- - Use canonical script names: `lint`, `format:check`, `typecheck`, `test`, `audit`, `validate`
195
- - Enforce quality gates before completion: `test`, `lint`, `format:check`, `typecheck`, `audit`
196
- - Use the `git-ops` skill for branch management, rebase, and conflict resolution
197
- - `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.
198
- - 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`.
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 `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.
209
114
 
210
115
  #### Write Scope (RF-62)
211
116
 
212
- An `architecture-change` task **MAY** modify:
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
- - `catalog/components/*.json` — generated by CI from component-repo extraction; never hand-edited or agent-edited
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 **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.
228
124
 
229
125
  #### ADR Requirement
230
126
 
231
- Before opening any meta-repo PR under the `architecture-change` task type, the agent **MUST** produce an Architecture Decision Record (ADR) containing:
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
- - PRs from the `architecture-change` task type targeting the meta-repo **REQUIRE** explicit human review and approval.
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. 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:
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 (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.
259
144
 
260
145
  ### Partitioning Procedure
261
146
 
262
- 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**.
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 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.
265
150
 
266
151
  ### Contract-as-Interface
267
152
 
268
- - Each sub-task uses the **boundary contract** (with a target version) as its interface.
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 **producer-before-consumers**:
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` confidence before it can serve as an acceptance boundary. This is achieved by:
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 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:
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 with normal task planning.
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 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).