brdohman/workflow-comments
.claude/skills/workflow/workflow-comments/SKILL.md
Comment structure and rules for task workflow updates. Use when adding any comment to a task during implementation, review, or fix cycles.
$ install --global
skillsauthnpx skillsauth add brdohman/agile-maestro workflow-commentsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 24, 2026, 8:57 PM1.7s1 file scanned
SKILL.md
- name:
- workflow-comments
- description:
- Comment structure and rules for task workflow updates. Use when adding any comment to a task during implementation, review, or fix cycles.
- allowed-tools:
- [TaskGet, TaskUpdate]
Workflow Comments
Comment Types
| Type | When Used | Who Writes It |
|------|-----------|---------------|
| note | General observation, starting claim | Any agent |
| implementation | Task work complete | macos-developer-agent, data-architect-agent |
| testing | Test results documented | macos-developer-agent, qa-agent |
| handoff | Story ready for next stage | macos-developer-agent |
| review | Stage passed (code-review, qa, product-review) | staff-engineer-agent, qa-agent, pm-agent |
| rejection | Stage failed — issues found | staff-engineer-agent, qa-agent, pm-agent, security-agent |
| fix | Rejection issues addressed, resubmitting | macos-developer-agent |
Comment Structures
Base comment (all non-rejection types)
{
"id": "C3",
"timestamp": "2026-02-21T10:00:00Z",
"author": "macos-developer-agent",
"type": "implementation",
"content": "IMPLEMENTATION COMPLETE\n\nFiles changed:\n- app/MyApp/MyApp/Views/ItemView.swift\n\nBuild: passed, Tests: 12/12"
}
Trackable comment (rejection only)
{
"id": "C4",
"timestamp": "2026-02-21T11:00:00Z",
"author": "staff-engineer-agent",
"type": "rejection",
"content": "REJECTED - CODE REVIEW\n\n1. Force unwrap on line 42 of ItemView.swift — use guard let",
"resolved": false,
"resolved_by": null,
"resolved_at": null
}
The resolved fields exist only on rejections — they are actionable items to track. When the developer fixes the issues, the reviewer sets resolved: true, resolved_by, and resolved_at.
Key Rules
- Read before write — always call
TaskGetfirst;commentsis append-only, spread existing array - Sequential IDs — read existing comments, use next number (if C3 exists, use C4)
- Every workflow field change requires a comment —
review_stage,review_result,blocked,approvalchanges must have a comment in the sameTaskUpdate - ISO 8601 timestamps — use full datetime with timezone:
2026-02-21T10:00:00Z - Structured objects only — never use plain string comments
Cross-References
- For stage-specific comment templates: see skill
review-cycle - For comment field reference and Protocol 6: see
.claude/rules/global/task-state-updates.md
Related Skills
brdohman/xctest-patterns
testing
VerifiedTrustedCommunity
XCTest patterns for macOS Swift apps. Unit tests, async tests, Core Data tests, mock patterns, and assertion reference. Use when writing or reviewing tests.
2SKILL.mdUpdated Apr 16, 2026
brdohman/workflow-state
tools
VerifiedTrustedCommunity
How to transition workflow state between review stages. Rules for setting review_stage and review_result fields on Stories and Epics.
2SKILL.mdUpdated Apr 16, 2026
brdohman/validate-task
testing
VerifiedTrustedCommunity
Validate task/story/epic/bug/techdebt metadata against schema v2.0. Run after TaskCreate or TaskUpdate to verify compliance. Returns pass/fail with actionable details.
2SKILL.mdUpdated Apr 16, 2026
brdohman/v2-schema-reference
data-ai
VerifiedTrustedCommunity
Canonical v2.0 metadata schema field reference for epics, stories, and tasks. Use when creating or validating task metadata.
2SKILL.mdUpdated Apr 16, 2026