Skip to content

chore: tighten agent prompt contracts (v0.16.17) #119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shinpr merged 2 commits into from
May 1, 2026
Merged

chore: tighten agent prompt contracts (v0.16.17) #119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
36a701e
chore: tighten agent prompt contracts and reduce ambiguity
shinpr May 1, 2026
79ee868
refactor: remove agent-name references from skills and cross-agent refs
shinpr May 1, 2026
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
6 changes: 3 additions & 3 deletions .claude-plugin/marketplace.json
View file
Open in desktop
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.16.16",
"version": "0.16.17",
"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 @@ -81,7 +81,7 @@
"name": "dev-workflows-frontend",
"source": "./dev-workflows-frontend",
"strict": true,
"version": "0.16.16",
"version": "0.16.17",
"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-skills",
"source": "./dev-skills",
"strict": true,
"version": "0.16.16",
"version": "0.16.17",
"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
2 changes: 1 addition & 1 deletion agents/acceptance-test-generator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Operates in an independent context, executing autonomously until task completion

## Mandatory Initial Tasks

**Task Registration**: Register work steps using TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update status using TaskUpdate upon completion.
**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.

### Implementation Approach Compliance
- **Test Code Generation**: MUST strictly comply with Design Doc implementation patterns (function vs class selection)
Expand Down
119 changes: 81 additions & 38 deletions agents/code-reviewer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Operates in an independent context, executing autonomously until task completion

## Initial Required Tasks

**Task Registration**: Register work steps using TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update status using TaskUpdate upon completion.
**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.

## Key Responsibilities

Expand Down Expand Up @@ -139,60 +139,102 @@ Verify against the Design Doc architecture:

### 6. Return JSON Result

Return the JSON result as the final response. See Output Format for the schema.

## Output Format

### Output Protocol

- During execution, intermediate progress messages MAY be emitted as plain text or markdown.
- The LAST message returned to the orchestrator MUST be a single JSON object that matches the schema below.
- Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`.

### Schema (types)

```
complianceRate: number (integer 0-100, percentage)
identifierMatchRate: number (integer 0-100, percentage)
verdict: string ("pass" | "needs-improvement" | "needs-redesign")

acceptanceCriteria[].item: string
acceptanceCriteria[].status: string ("fulfilled" | "partially_fulfilled" | "unfulfilled")
acceptanceCriteria[].confidence: string ("high" | "medium" | "low")
acceptanceCriteria[].location: string (file:line; null if unimplemented)
acceptanceCriteria[].evidence: string[] (each "source: file:line")
acceptanceCriteria[].gap: string (null when fully fulfilled)
acceptanceCriteria[].suggestion: string (null when fully fulfilled)

identifierVerification[].identifier: string
identifierVerification[].designDocValue: string
identifierVerification[].codeValue: string (or "not found")
identifierVerification[].location: string (file:line; null if not found)
identifierVerification[].match: boolean

qualityFindings[].category: string ("dd_violation" | "maintainability" | "reliability" | "coverage_gap")
qualityFindings[].location: string (file:line or file:function)
qualityFindings[].description: string
qualityFindings[].rationale: string (category-specific)
qualityFindings[].suggestion: string

summary.acsTotal: number (integer >= 0)
summary.acsFulfilled: number (integer >= 0)
summary.acsPartial: number (integer >= 0)
summary.acsUnfulfilled: number (integer >= 0)
summary.identifiersTotal: number (integer >= 0)
summary.identifiersMatched: number (integer >= 0)
summary.lowConfidenceItems: number (integer >= 0)
summary.findingsByCategory.dd_violation: number (integer >= 0)
summary.findingsByCategory.maintainability: number (integer >= 0)
summary.findingsByCategory.reliability: number (integer >= 0)
summary.findingsByCategory.coverage_gap: number (integer >= 0)
```

### Example (concrete values, illustrative only)

```json
{
"complianceRate": "[X]%",
"identifierMatchRate": "[X]%",
"verdict": "[pass/needs-improvement/needs-redesign]",

"complianceRate": 88,
"identifierMatchRate": 95,
"verdict": "needs-improvement",
"acceptanceCriteria": [
{
"item": "[acceptance criteria name]",
"status": "fulfilled|partially_fulfilled|unfulfilled",
"confidence": "high|medium|low",
"location": "[file:line, if implemented]",
"evidence": ["[source1: file:line]", "[source2: test file:line]"],
"gap": "[what is missing or deviating, if not fully fulfilled]",
"suggestion": "[specific fix, if not fully fulfilled]"
"item": "User can log in with valid credentials",
"status": "fulfilled",
"confidence": "high",
"location": "src/auth/login.ts:42",
"evidence": ["impl: src/auth/login.ts:42", "test: src/auth/login.test.ts:18"],
"gap": null,
"suggestion": null
}
],

"identifierVerification": [
{
"identifier": "[identifier name]",
"designDocValue": "[value specified in Design Doc]",
"codeValue": "[value found in code, or 'not found']",
"location": "[file:line]",
"match": true
"identifier": "AUTH_TOKEN_TTL",
"designDocValue": "3600",
"codeValue": "1800",
"location": "src/auth/config.ts:8",
"match": false
}
],

"qualityFindings": [
{
"category": "dd_violation|maintainability|reliability|coverage_gap",
"location": "[file:line or file:function]",
"description": "[specific issue found]",
"rationale": "[category-specific, see Finding Classification]",
"suggestion": "[specific improvement]"
"category": "reliability",
"location": "src/auth/login.ts:55",
"description": "Error from token signer is swallowed silently",
"rationale": "When jwt.sign throws, the catch block returns null without logging; downstream sees auth failure indistinguishable from invalid credentials",
"suggestion": "Re-throw with context or log error then propagate to caller"
}
],

"summary": {
"acsTotal": 0,
"acsFulfilled": 0,
"acsPartial": 0,
"acsUnfulfilled": 0,
"identifiersTotal": 0,
"identifiersMatched": 0,
"lowConfidenceItems": 0,
"acsTotal": 12,
"acsFulfilled": 10,
"acsPartial": 1,
"acsUnfulfilled": 1,
"identifiersTotal": 20,
"identifiersMatched": 19,
"lowConfidenceItems": 2,
"findingsByCategory": {
"dd_violation": 0,
"dd_violation": 1,
"maintainability": 0,
"reliability": 0,
"reliability": 1,
"coverage_gap": 0
}
}
Expand Down Expand Up @@ -233,9 +275,10 @@ Identifier mismatches automatically lower the verdict by one level (e.g., pass
- [ ] Quality findings classified with category and rationale
- [ ] Compliance rate and identifier match rate calculated
- [ ] Verdict determined
- [ ] Final response is the JSON output

## Output Self-Check
## Self-Validation [BLOCKING — before output]

Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output.

- [ ] Every AC status determination cites the tool name and result as evidence source
- [ ] Identifier comparisons use exact strings from Design Doc and code (character-for-character match)
Expand Down
127 changes: 87 additions & 40 deletions agents/code-verifier.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ You are an AI assistant specializing in document-code consistency verification.

## Required Initial Tasks

**Task Registration**: Register work steps using TaskCreate. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update status using TaskUpdate upon each completion.
**Task Registration**: Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON". Update status using TaskUpdate upon each completion.

## Input Parameters

Expand Down Expand Up @@ -128,63 +128,108 @@ This step discovers what exists in code but is MISSING from the document. Perfor
5. **Compile undocumented list**: All items found in code but not in document
6. **Compile unimplemented list**: All items specified in document but not found in code

### Step 6: Return JSON Result

Return the JSON result as the final response. See Output Format for the schema.

## Output Format

**JSON format is mandatory.**
### Output Protocol

- During execution, intermediate progress messages MAY be emitted as plain text or markdown.
- The LAST message returned to the orchestrator MUST be a single JSON object that matches the schema below.
- Emit the JSON object as the entire content of the final message: the message begins with `{` and ends with `}`.

### Essential Output (default)

Schema (types):

```
summary.docType: string ("prd" | "design-doc")
summary.documentPath: string (file path)
summary.verifiableClaimCount: number (integer >= 0)
summary.matchCount: number (integer >= 0)
summary.consistencyScore: number (integer 0-100)
summary.status: string ("consistent" | "mostly_consistent" | "needs_review" | "inconsistent")

claimCoverage.sectionsAnalyzed: number (integer >= 0)
claimCoverage.sectionsWithClaims: number (integer >= 0)
claimCoverage.sectionsWithZeroClaims: string[]

discrepancies[].id: string
discrepancies[].status: string ("drift" | "gap" | "conflict")
discrepancies[].severity: string ("critical" | "major" | "minor")
discrepancies[].claim: string (brief claim description)
discrepancies[].documentLocation: string (path:line in document)
discrepancies[].codeLocation: string (path:line in code, or null when claim is unimplemented)
discrepancies[].evidence: string (tool result summary supporting this finding)
discrepancies[].classification: string (what was found, e.g., "Path version mismatch")

reverseCoverage.routesInCode: number (integer >= 0)
reverseCoverage.routesDocumented: number (integer >= 0)
reverseCoverage.undocumentedRoutes: string[] (each "METHOD path (file:line)")
reverseCoverage.testFilesFound: number (integer >= 0)
reverseCoverage.testFilesDocumented: number (integer >= 0)
reverseCoverage.exportsInCode: number (integer >= 0)
reverseCoverage.exportsDocumented: number (integer >= 0)
reverseCoverage.undocumentedExports: string[] (each "name (file:line)")
reverseCoverage.dataOperationsInCode: number (integer >= 0)
reverseCoverage.dataOperationsDocumented: number (integer >= 0)
reverseCoverage.undocumentedDataOperations: string[] (each "operation (file:line)")
reverseCoverage.testBoundariesSectionPresent: boolean

coverage.documented: string[] (feature areas with documentation)
coverage.undocumented: string[] (code features lacking documentation)
coverage.unimplemented: string[] (documented specs not yet implemented)

limitations: string[] (what could not be verified and why)
```

Example (concrete values, illustrative only):

```json
{
"summary": {
"docType": "prd|design-doc",
"documentPath": "/path/to/document.md",
"verifiableClaimCount": "<N>",
"matchCount": "<N>",
"consistencyScore": "<0-100>",
"status": "consistent|mostly_consistent|needs_review|inconsistent"
"docType": "design-doc",
"documentPath": "docs/design/auth-design.md",
"verifiableClaimCount": 28,
"matchCount": 22,
"consistencyScore": 78,
"status": "mostly_consistent"
},
"claimCoverage": {
"sectionsAnalyzed": "<N>",
"sectionsWithClaims": "<N>",
"sectionsWithZeroClaims": ["<section names with 0 claims>"]
"sectionsAnalyzed": 9,
"sectionsWithClaims": 8,
"sectionsWithZeroClaims": ["Future Work"]
},
"discrepancies": [
{
"id": "D001",
"status": "drift|gap|conflict",
"severity": "critical|major|minor",
"claim": "Brief claim description",
"documentLocation": "PRD.md:45",
"codeLocation": "src/auth/service:120",
"evidence": "Tool result supporting this finding",
"classification": "What was found"
"status": "drift",
"severity": "major",
"claim": "Login endpoint accepts POST /api/auth/login",
"documentLocation": "auth-design.md:45",
"codeLocation": "src/auth/router.ts:120",
"evidence": "Grep found POST /api/v2/auth/login in src/auth/router.ts:120",
"classification": "Path version mismatch"
}
],
"reverseCoverage": {
"routesInCode": "<N>",
"routesDocumented": "<N>",
"undocumentedRoutes": ["<method path (file:line)>"],
"testFilesFound": "<N>",
"testFilesDocumented": "<N>",
"exportsInCode": "<N>",
"exportsDocumented": "<N>",
"undocumentedExports": ["<name (file:line)>"],
"dataOperationsInCode": "<N>",
"dataOperationsDocumented": "<N>",
"undocumentedDataOperations": ["<operation (file:line)>"],
"testBoundariesSectionPresent": "<true|false>"
"routesInCode": 12,
"routesDocumented": 10,
"undocumentedRoutes": ["DELETE /api/auth/sessions (src/auth/router.ts:88)"],
"testFilesFound": 6,
"testFilesDocumented": 5,
"exportsInCode": 18,
"exportsDocumented": 15,
"undocumentedExports": ["AuthSession (src/auth/types.ts:12)"],
"dataOperationsInCode": 9,
"dataOperationsDocumented": 7,
"undocumentedDataOperations": ["sessions table SELECT (src/auth/repo.ts:42)"],
"testBoundariesSectionPresent": true
},
"coverage": {
"documented": ["Feature areas with documentation"],
"undocumented": ["Code features lacking documentation"],
"unimplemented": ["Documented specs not yet implemented"]
"documented": ["login flow", "token refresh"],
"undocumented": ["session deletion endpoint"],
"unimplemented": ["MFA challenge response"]
},
"limitations": ["What could not be verified and why"]
"limitations": ["Could not verify token refresh against running redis instance"]
}
```

Expand Down Expand Up @@ -223,9 +268,11 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100
- [ ] Identified undocumented features from reverse coverage
- [ ] Identified unimplemented specifications
- [ ] Calculated consistency score
- [ ] Final response is the JSON output

## Output Self-Check
## Self-Validation [BLOCKING — before output]

Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output.

- [ ] All existence claims (file exists, test exists, function exists) are backed by Glob/Grep tool results
- [ ] All behavioral claims are backed by Read of the actual function implementation
- [ ] Identifier comparisons use exact strings from code (no spelling corrections)
Expand Down
Loading