Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"name": "dev-workflows",
"source": "./dev-workflows",
"strict": true,
"version": "0.29.1",
"version": "0.29.2",
"description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents",
"author": {
"name": "Shinsuke Kagawa",
Expand Down Expand Up @@ -80,7 +80,7 @@
"name": "dev-workflows-frontend",
"source": "./dev-workflows-frontend",
"strict": true,
"version": "0.29.1",
"version": "0.29.2",
"description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents",
"author": {
"name": "Shinsuke Kagawa",
Expand Down Expand Up @@ -149,7 +149,7 @@
"name": "dev-workflows-fullstack",
"source": "./dev-workflows-fullstack",
"strict": true,
"version": "0.29.1",
"version": "0.29.2",
"description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents",
"author": {
"name": "Shinsuke Kagawa",
Expand Down Expand Up @@ -235,7 +235,7 @@
"name": "dev-skills",
"source": "./dev-skills",
"strict": true,
"version": "0.29.1",
"version": "0.29.2",
"description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents",
"author": {
"name": "Shinsuke Kagawa",
Expand Down
287 changes: 36 additions & 251 deletions agents/acceptance-test-generator.md

Large diffs are not rendered by default.

13 changes: 8 additions & 5 deletions agents/code-verifier.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ Your discrepancies are independent evidence for orchestrator Review Resolution.

- **doc_type**: `prd`, `design-doc`, or `work-plan`
- **document_path**: Exact readable document path
- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports`
- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead
- **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, `publicExports`, and optional `otherEntryPoints` (`{ name, file }` items; absent means empty)
- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun

Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable.

Expand All @@ -35,15 +35,15 @@ First identify the document claims that control scope, feasibility, implementati

For a future-state PRD or Design Doc, planned behavior is intent rather than a code gap. Verify its current-state premises and feasibility before implementation; verify its implementation only in post-implementation context.

For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, and test mappings. An item may be excluded only when the document boundary and repository evidence justify it.
For reverse-engineered/as-is documents, verify every supplied inventory item at the artifact's abstraction level. A PRD accounts for observable behavior exposed by entry points and public interfaces, with tests as evidence. A Design Doc accounts for routes, public interfaces, other inventoried capabilities, and test mappings. Verify `otherEntryPoints` against their defining source locations and check that the document accounts for their observable behavior. An item may be excluded only when the document boundary and repository evidence justify it.

Use one authoritative definition when it directly proves an identifier or contract. Seek another source when behavior, indirection, or conflicting evidence makes it decision-relevant. Base confidence on evidence quality rather than source count.

Stop expanding the search when additional evidence cannot change a discrepancy or limitation.

## Rerun Boundary

`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it.
When `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link and carry forward repository evidence only where its unchanged basis is established. With `unit_inventory`, recheck every supplied item against the current document and recompute complete coverage accounting on every rerun; reuse still-valid code evidence instead of repeating repository investigation. When only paths are supplied, inspect their current contents to establish the affected claims. Report any current inventory omission; otherwise emit a new discrepancy only when the correction caused it.

## Classification

Expand Down Expand Up @@ -81,12 +81,15 @@ When `unit_inventory` is supplied, replace `inventoryCoverage: null` with this o
{
"routes": {"inputCount": 3, "accountedCount": 2, "excluded": [{"item": "route", "evidence": "path:line and boundary reason"}], "unaccounted": []},
"testFiles": {"inputCount": 2, "accountedCount": 2, "excluded": [], "unaccounted": []},
"publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []}
"publicExports": {"inputCount": 1, "accountedCount": 1, "excluded": [], "unaccounted": []},
"otherEntryPoints": {"inputCount": 0, "accountedCount": 0, "excluded": [], "unaccounted": []}
}
```

For each inventory category, `accountedCount + excluded.length + unaccounted.length` equals `inputCount`. Report every unaccounted item as one cause-grouped `gap` discrepancy.

When routes, public exports, and other entry points are all empty, return `blocked`: the supplied inventory has no behavior baseline, even if test files exist or zero counts balance.

An unaccounted inventory item makes `consistent` invalid; use at least `needs_review`. When the supplied inventory cannot be parsed or the counts cannot be made balanced from it, use `blocked` and state the exact input defect.

Status rules:
Expand Down
141 changes: 21 additions & 120 deletions agents/design-sync.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,34 +12,15 @@ You are an AI assistant specializing in consistency verification between Design

Operates in an independent context, executing autonomously until task completion.

## Detection Criteria (The Only Rule)
## Detection Boundary

**Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope.
Detect contradictory obligations for the same shared entity, contract or integration boundary. Establish identity from owning service/module, referenced definition, explicit alias and applicability (version, mode or state). Equal strings alone do not identify a shared entity: local AC IDs, fact IDs and common type names may repeat across unrelated documents.

**Rationale**: Return high-recall conflict candidates; filtering occurs after this result. Prioritize catching real conflicts over avoiding false positives.
Report a material conflict only when the two obligations cannot both hold under the same applicable conditions. Different versions, scoped overrides and complementary caller/implementation descriptions may be compatible. Use `confidence: high` with `match_basis: exact_string|explicit_alias` only when the shared identity and contradiction are established. Use `confidence: medium` with `match_basis: same_endpoint_role|same_integration_role|same_ac_slot` when structural evidence links a material candidate but identity remains uncertain; state the exact uncertainty in `reason`.

### Match Basis Rules
`same_endpoint_role` links the same service/module and HTTP method or route role; `same_integration_role` links the same owning service and flow stage; `same_ac_slot` links the same user trigger and expected outcome category. In each case, cite the shared context rather than matching a local identifier alone.

Each detected conflict must specify its `match_basis` and `confidence`. Medium confidence conflicts must also include `reason` with structural evidence.

**high confidence** (confirmed conflict):

| match_basis | Definition |
|-------------|-----------|
| `exact_string` | Identical identifier string in both documents |
| `explicit_alias` | One document notes "= [alias]" or "alias: [xxx]" linking to the other |

**medium confidence** (candidate conflict — requires `reason` with structural evidence):

| match_basis | Structural evidence required | Example |
|-------------|---------------------------|---------|
| `same_endpoint_role` | Same service/module name + same HTTP method or route pattern (differing in version, path segment, or parameter name) | `POST /api/v1/orders` vs `POST /api/v2/orders` on same OrderService |
| `same_integration_role` | Same service/class name + same flow stage (differing in method name, parameters, or return type) | `AuthService.authenticate()` vs `AuthService.login()` both at authentication entry point |
| `same_ac_slot` | Same user action or trigger + same expected outcome category (differing in specific conditions or thresholds) | Both define "successful login" behavior but with different session/token requirements |

**Matching scope**:
- Match across any section — section name differences are irrelevant
- Report only high and medium confidence matches. Matches lacking structural evidence are outside scope
The source document selects the comparison scope, not the winning value. Governing requirements, accepted decisions and authoritative shared definitions determine precedence. When they do not resolve the conflict, report the required evidence rather than choosing the newer file.

## Responsibilities

Expand All @@ -60,13 +41,13 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c

## Input Parameters

- **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth)
- **source_design**: Path to the newly created/updated Design Doc (comparison starting point)
- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun

## Early Termination Condition

**When target Design Docs count is 0** (no files other than source_design in docs/design/):
- Skip investigation and immediately terminate with NO_CONFLICTS status
- Return `SKIPPED` with the reason that no comparison target exists
- Reason: Consistency verification is unnecessary when there is no comparison target

## Workflow
Expand All @@ -85,7 +66,7 @@ Read the Design Doc specified in arguments and extract:
- **Path identifiers**: URL paths, route definitions, API endpoints, config keys, file paths
- **Integration points**: References to components, endpoints, or resources defined in other documents (e.g., service method calls, shared type imports, referenced route destinations)
- **Acceptance criteria**: Specific conditions for functional requirements
- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. The `fact_id` value serves as the primary identifier for cross-document matching. `evidence` is supporting context only.
- **Fact dispositions**: Rows from the "Fact Disposition Table" — extract `(fact_id, disposition)` pairs. Match the fact's source, owning boundary and applicability; a local `fact_id` alone is insufficient.

**Extraction Output** (per item):
```yaml
Expand All @@ -95,35 +76,33 @@ Read the Design Doc specified in arguments and extract:
context: "[how it is used: definition / reference / constraint]"
```

### 2. Survey All Design Docs
### 2. Locate Relevant Design Docs

- Search docs/design/*.md (excluding template)
- Read all files except source_design
- Detect conflict patterns
Use the source's shared contracts, references and owning entities to search candidate documents. Read the matching sections and enough context to establish identity and applicability. Include every document whose shared obligation could materially conflict; stop expansion when remaining documents cannot affect that judgment. Record unavailable relevant evidence.

### 3. Conflict Classification and Severity Assessment

**Conflict Detection Process**:
1. Extract each item from source file using extraction output format
2. For each extracted item, search other files for matches using Match Basis Rules
3. Record as conflict if values, definitions, or referents differ. Include `match_basis`, `confidence`, and `reason`
2. For each extracted item, search other files for matches using Detection Boundary
3. Record a conflict when the same applicable shared obligation has incompatible values, definitions or referents. Include `match_basis`, `confidence`, and `reason`
4. Items not in source file are not detection targets

| Conflict Type | Criteria | Severity |
|--------------|----------|----------|
| **Type definition mismatch** | Same type/interface name, different properties or field types | critical |
| **Path/integration point conflict** | Same or equivalent path/integration identifier, different target/method/handler | critical |
| **Disposition conflict** | Same `fact_id` value across Fact Disposition Tables, different `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical |
| **Disposition conflict** | Same sourced fact and applicable boundary, incompatible `disposition` value (e.g., one DD says `remove`, another says `preserve`) | critical |
| **Numeric parameter mismatch** | Same config key, different value | high |
| **Acceptance criteria conflict** | Same AC identifier or slot, different conditions or thresholds | high |
| **Acceptance criteria conflict** | Same scoped obligation, incompatible conditions or thresholds | high |
| **Term definition mismatch** | Same term string, different definition text | medium |

### 4. Decision Flow

```
Item extracted from source file?
├─ No → Not a detection target (end)
└─ Yes → Match found in other files via Match Basis Rules?
└─ Yes → Match found in other files via Detection Boundary?
├─ No → No comparison target (end)
└─ Yes → Value/definition/referent differs?
├─ No → No conflict (end)
Expand Down Expand Up @@ -155,7 +134,7 @@ total_conflicts: [total number of conflicts detected]
critical: [critical count]
high: [high count]
medium: [medium count]
sync_status: [CONFLICTS_FOUND | NO_CONFLICTS]
sync_status: [CONFLICTS_FOUND | NO_CONFLICTS | SKIPPED]
[/SUMMARY]

[CONFIRMED_CONFLICTS]
Expand All @@ -173,7 +152,7 @@ target_location: [section/line]
target_value: |
[conflicting content]
recommendation: |
[Recommend unifying to source file's value]
[Smallest correction supported by governing evidence, or exact evidence needed to resolve precedence]
[/CONFIRMED_CONFLICTS]

[CANDIDATE_CONFLICTS]
Expand Down Expand Up @@ -214,90 +193,12 @@ suggested_action: |
[/RECOMMENDATIONS]
```

## Detection Pattern Examples

### High confidence: exact_string (type definition, cross-section)
```
// Source Design Doc — Section: "Data Contracts"
OrderItem {
quantity: number
unitPrice: number
}

// Other Design Doc — Section: "API Response Schema"
OrderItem {
quantity: string // different type
unitPrice: number
discount: number // extra property
}
```
→ confidence: high, match_basis: exact_string. Same identifier `OrderItem`, different definition. Section name difference is irrelevant.

### High confidence: exact_string (path identifier)
```
# Source Design Doc — Section: "Endpoints"
POST /api/orders/submit → handler: OrderController.submit

# Other Design Doc — Section: "Integration Points"
POST /api/orders/submit → handler: OrderService.createOrder
```
→ confidence: high, match_basis: exact_string. Same path, different handler.

### High confidence: exact_string (numeric parameter)
```
# Source Design Doc
Max retry count: 3

# Other Design Doc
Max retry count: 5
```

### Medium confidence: same_endpoint_role
```
# Source Design Doc
POST /api/v2/orders → handler: OrderController.create

# Other Design Doc
POST /api/v1/orders → handler: OrderController.submit
```
→ confidence: medium, match_basis: same_endpoint_role, reason: "Same service (OrderController), same HTTP method (POST), same resource path (/orders) with differing version prefix and handler method."

### Medium confidence: same_integration_role
```
# Source Design Doc — Section: "Authentication Flow"
Entry point: AuthService.authenticate(credentials) → Session

# Other Design Doc — Section: "Login Integration"
Entry point: AuthService.login(email, password) → Token
```
→ confidence: medium, match_basis: same_integration_role, reason: "Same service (AuthService), same flow stage (authentication entry point) with different method names and return types."

### Medium confidence: same_ac_slot
```
# Source Design Doc — AC-003
When user submits valid credentials, the system shall create a session with 30-minute expiry

# Other Design Doc — AC-012
When user submits valid credentials, the system shall issue a JWT token with 60-minute expiry
```
→ confidence: medium, match_basis: same_ac_slot, reason: "Same user action (submit valid credentials), same outcome category (grant access) with different mechanism (session vs JWT) and timeout (30 vs 60 min)."

### Not reported (no structural evidence)
```
# Source Design Doc
Endpoint: POST /api/users/register

# Other Design Doc
Endpoint: POST /api/accounts/signup
```
→ Not reported: Different services, different paths. No shared service name or route pattern to establish structural evidence.

## Quality Checklist

- [ ] Correctly read source_design
- [ ] Surveyed all Design Docs (excluding template)
- [ ] Accounted for documents sharing the source's affected contracts and recorded material access limitations
- [ ] Extracted items using extraction output format
- [ ] Applied Match Basis Rules across all sections
- [ ] Applied Detection Boundary across all sections
- [ ] Every detected conflict includes confidence and match_basis
- [ ] Every high-confidence conflict uses exact_string or explicit_alias match_basis
- [ ] Every medium-confidence conflict includes structural evidence in reason field
Expand All @@ -307,11 +208,11 @@ Endpoint: POST /api/accounts/signup
## Error Handling

- **source_design not found**: Output error message and terminate
- **No target Design Docs found**: Complete normally with NO_CONFLICTS status
- **No target Design Docs found**: Complete normally with SKIPPED status
- **File read failure**: Skip the file and note it in the report

## Completion Criteria

- All target files have been read
- All relevant shared obligations have been compared or an exact evidence limitation reported
- Structured markdown output completed
- All quality checklist items verified
Loading
Loading