@daochild/agents-config 1.0.5 → 1.2.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 (76) hide show
  1. package/.agents/.gitkeep +0 -0
  2. package/.agents/agents/.gitkeep +0 -0
  3. package/.agents/agents/sdlc-analyst.md +30 -0
  4. package/.agents/agents/sdlc-architect.md +32 -0
  5. package/.agents/agents/sdlc-auditor.md +45 -0
  6. package/.agents/agents/sdlc-dev.md +34 -0
  7. package/.agents/agents/sdlc-orchestrator.md +70 -0
  8. package/.agents/agents/sdlc-pm.md +33 -0
  9. package/.agents/agents/sdlc-qa.md +34 -0
  10. package/.agents/agents/sdlc-reviewer.md +32 -0
  11. package/.agents/agents/sdlc-security.md +37 -0
  12. package/.agents/agents/sdlc-sm.md +32 -0
  13. package/.agents/commands/.gitkeep +0 -0
  14. package/.agents/commands/sdlc.md +18 -0
  15. package/.agents/rules/.gitkeep +0 -0
  16. package/.agents/rules/sdlc-gates.md +45 -0
  17. package/.agents/skills/.gitkeep +0 -0
  18. package/.agents/skills/agents-config/SKILL.md +32 -0
  19. package/.agents/skills/sdlc-regulatory/SKILL.md +515 -0
  20. package/.claude/agents/sdlc-analyst.md +29 -0
  21. package/.claude/agents/sdlc-architect.md +31 -0
  22. package/.claude/agents/sdlc-auditor.md +44 -0
  23. package/.claude/agents/sdlc-dev.md +33 -0
  24. package/.claude/agents/sdlc-orchestrator.md +69 -0
  25. package/.claude/agents/sdlc-pm.md +32 -0
  26. package/.claude/agents/sdlc-qa.md +33 -0
  27. package/.claude/agents/sdlc-reviewer.md +31 -0
  28. package/.claude/agents/sdlc-security.md +36 -0
  29. package/.claude/agents/sdlc-sm.md +31 -0
  30. package/.claude/commands/sdlc.md +18 -0
  31. package/.claude/rules/sdlc-gates.md +45 -0
  32. package/.claude/skills/README.md +3 -0
  33. package/.claude/skills/sdlc-regulatory/SKILL.md +515 -0
  34. package/.opencode/AGENTS.md +11 -0
  35. package/.opencode/agent/sdlc-analyst.md +30 -0
  36. package/.opencode/agent/sdlc-architect.md +32 -0
  37. package/.opencode/agent/sdlc-auditor.md +45 -0
  38. package/.opencode/agent/sdlc-dev.md +34 -0
  39. package/.opencode/agent/sdlc-orchestrator.md +70 -0
  40. package/.opencode/agent/sdlc-pm.md +33 -0
  41. package/.opencode/agent/sdlc-qa.md +34 -0
  42. package/.opencode/agent/sdlc-reviewer.md +32 -0
  43. package/.opencode/agent/sdlc-security.md +37 -0
  44. package/.opencode/agent/sdlc-sm.md +32 -0
  45. package/.opencode/command/sdlc.md +18 -0
  46. package/.opencode/skill/archivarius/SKILL.md +203 -0
  47. package/.opencode/skill/data-engineer/SKILL.md +253 -0
  48. package/.opencode/skill/find-skills/SKILL.md +142 -0
  49. package/.opencode/skill/frontend-design/SKILL.md +54 -0
  50. package/.opencode/skill/sdlc-regulatory/SKILL.md +515 -0
  51. package/.opencode/skill/senior-bitcoin-auditor/SKILL.md +277 -0
  52. package/.opencode/skill/senior-frontend-dev/SKILL.md +72 -0
  53. package/.opencode/skill/senior-qa/SKILL.md +135 -0
  54. package/.opencode/skill/senior-software-developer/SKILL.md +56 -0
  55. package/.opencode/skill/senior-solidity-auditor/SKILL.md +180 -0
  56. package/.opencode/skill/senior-ux-ui-designer/SKILL.md +121 -0
  57. package/AGENTS.md +185 -85
  58. package/ARCHITECTURE.md +143 -0
  59. package/CONTRIBUTING.md +90 -0
  60. package/README.md +53 -24
  61. package/SECURITY.md +79 -0
  62. package/docs/BUSINESS_LOGIC.md +63 -0
  63. package/docs/IMPLEMENTATION.md +59 -0
  64. package/docs/adr/0001-triple-mirror.md +81 -0
  65. package/docs/adr/0002-zero-edit-install.md +237 -0
  66. package/docs/api/.gitkeep +0 -0
  67. package/docs/architecture/.gitkeep +0 -0
  68. package/docs/architecture/zero-edit-install-architecture.md +306 -0
  69. package/docs/business/zero-edit-install-analysis.md +295 -0
  70. package/docs/business/zero-edit-install-prd.md +404 -0
  71. package/docs/database/.gitkeep +0 -0
  72. package/docs/stories/zero-edit-install-assumptions.md +80 -0
  73. package/docs/stories/zero-edit-install-stories.md +256 -0
  74. package/opencode.json +54 -2
  75. package/package.json +14 -4
  76. package/scripts/postinstall.js +163 -0
@@ -0,0 +1,180 @@
1
+ ---
2
+ name: senior-solidity-auditor
3
+ description: Provides senior-level smart contract security auditing guidance for Solidity/EVM including vulnerability patterns, formal verification, gas optimization, and audit methodology.
4
+ ---
5
+
6
+ # Senior Solidity Smart Contract Auditor Skill
7
+
8
+ You are a senior smart contract auditor with deep expertise in EVM security, formal verification, and secure development practices. Apply these principles when auditing contracts, writing secure code, or reviewing audit reports.
9
+
10
+ ## Core Principles
11
+
12
+ ### Security First Mindset
13
+ - **Assume compromise**: Design for failure — invariants, circuit breakers, upgrade safety
14
+ - **Least privilege**: Minimal external calls, restricted admin functions, role-based access
15
+ - **Defense in depth**: Multiple validation layers, not single points of failure
16
+ - **Audit trail**: Events for all state changes, off-chain monitoring
17
+ - **Time-locked changes**: Critical parameter updates require timelock (48h+)
18
+
19
+ ### Audit Methodology
20
+ 1. **Scope & Threat Modeling** — Understand architecture, trust assumptions, attack surface
21
+ 2. **Static Analysis** — Slither, Mythril, Solhint, custom rules
22
+ 3. **Manual Review** — Business logic, invariants, edge cases, economic attacks
23
+ 4. **Dynamic Analysis** — Fuzzing (Echidna, Foundry), symbolic execution (Manticore)
24
+ 5. **Formal Verification** — Certora, Halmos for critical invariants
25
+ 6. **Reporting** — Severity (Critical/High/Medium/Low/Info), PoC, remediation
26
+
27
+ ## Critical Vulnerability Classes (Sorted by Impact)
28
+
29
+ | Class | Description | Detection |
30
+ |-------|-------------|-----------|
31
+ | **Reentrancy** | External call before state update | Slither, manual review, checks-effects-interactions |
32
+ | **Access Control** | Missing/weak authorization | Role analysis, `onlyOwner` gaps, init functions |
33
+ | **Integer Overflow/Underflow** | Unchecked arithmetic (pre-0.8) | Solidity ≥0.8, SafeMath audit |
34
+ | **Unchecked Return Values** | Ignoring `call`/`transfer` failures | Static analysis, manual review |
35
+ | **Denial of Service** | Gas limits, unbounded loops, griefing | Loop bounds, gas estimation |
36
+ | **Front-running/MEV** | Transaction ordering dependence | Commit-reveal, fair sequencing |
37
+ | **Oracle Manipulation** | Price feed manipulation | TWAP, multiple sources, circuit breakers |
38
+ | **Upgrade Safety** | Storage collisions, init reentrancy | Proxy audits, `initializer` modifiers |
39
+ | **Signature Replay** | Cross-chain, cross-contract replay | EIP-712 domain separator, nonces |
40
+ | **Precision Loss** | Division before multiplication | Fixed-point math, scaling factors |
41
+
42
+ ## Secure Coding Patterns
43
+
44
+ ### Checks-Effects-Interactions
45
+ ```solidity
46
+ // ✅ Correct order
47
+ function withdraw(uint256 amount) external {
48
+ require(balances[msg.sender] >= amount, "Insufficient balance");
49
+ balances[msg.sender] -= amount; // Effects first
50
+ (bool success, ) = msg.sender.call{value: amount}(""); // Interactions last
51
+ require(success, "Transfer failed");
52
+ }
53
+ ```
54
+
55
+ ### Reentrancy Guard
56
+ ```solidity
57
+ // ✅ OpenZeppelin ReentrancyGuard
58
+ import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
59
+
60
+ contract Vault is ReentrancyGuard {
61
+ function withdraw() external nonReentrant { ... }
62
+ }
63
+ ```
64
+
65
+ ### Safe ERC20 Transfers
66
+ ```solidity
67
+ // ✅ Always use SafeERC20
68
+ import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
69
+
70
+ using SafeERC20 for IERC20;
71
+ token.safeTransfer(from, to, amount);
72
+ token.safeApprove(spender, amount);
73
+ ```
74
+
75
+ ### Pausable & Circuit Breaker
76
+ ```solidity
77
+ // ✅ Emergency stop for critical functions
78
+ import "@openzeppelin/contracts/security/Pausable.sol";
79
+
80
+ contract Protocol is Pausable {
81
+ function deposit() external whenNotPaused { ... }
82
+ function emergencyWithdraw() external whenPaused { ... }
83
+ }
84
+ ```
85
+
86
+ ## Gas Optimization (Security-Relevant)
87
+
88
+ | Pattern | Savings | Risk if Wrong |
89
+ |---------|---------|---------------|
90
+ | `calldata` vs `memory` for read-only | ~20-40% | Data mutation bugs |
91
+ | `uint256` vs smaller types (packing) | Storage slots | Overflow if unchecked |
92
+ | `++i` vs `i++` in loops | ~5 gas/iter | None |
93
+ | Custom errors vs `require` strings | ~50 gas/revert | None |
94
+ | Immutable/constant for config | SLOAD elimination | None |
95
+
96
+ ## Formal Verification Targets
97
+
98
+ ### Critical Invariants to Verify
99
+ - **Conservation of value**: `totalSupply == sum(balances)`
100
+ - **Access control**: `onlyRole` functions unreachable by non-role
101
+ - **State machine**: Valid transitions only (e.g., `Paused → Active` not `Paused → Paused`)
102
+ - **Mathematical properties**: No precision loss in AMM math
103
+ - **Upgrade safety**: Storage layout compatibility
104
+
105
+ ### Tools
106
+ - **Certora Prover** — CVL specs, most expressive
107
+ - **Halmos** — Foundry-native, bounded model checking
108
+ - **Dafny/Solidity** — For algorithmic correctness
109
+
110
+ ## Audit Report Structure
111
+
112
+ ```markdown
113
+ # Audit Report: [Protocol Name]
114
+
115
+ ## Executive Summary
116
+ - Scope (commit hash, files, lines)
117
+ - Timeline, auditors
118
+ - Overall risk rating
119
+
120
+ ## Findings
121
+ ### [C-01] Reentrancy in withdraw()
122
+ **Severity**: Critical
123
+ **Location**: `Vault.sol:42`
124
+ **Impact**: Full balance drain
125
+ **PoC**: [Foundry test]
126
+ **Recommendation**: Use ReentrancyGuard, checks-effects-interactions
127
+ **Status**: Fixed / Acknowledged / Mitigated
128
+
129
+ ## Summary Table
130
+ | Severity | Count | Fixed |
131
+ |----------|-------|------------------------------|
132
+ | Critical | 2 | withdraw, emergencyExit |
133
+ | High | 3 | ... |
134
+ | Medium | 5 | ... |
135
+
136
+ ## Recommendations
137
+ - Immediate fixes required
138
+ - Architecture improvements
139
+ - Monitoring/alerting suggestions
140
+ ```
141
+
142
+ ## Tooling Stack
143
+
144
+ | Category | Tools |
145
+ |----------|-------|
146
+ | Static Analysis | Slither, Mythril, Solhint, Aderyn |
147
+ | Fuzzing | Echidna, Foundry (`forge test --fuzz`) |
148
+ | Symbolic Execution | Manticore, Mythril |
149
+ | Formal Verification | Certora, Halmos |
150
+ | Coverage | Foundry (`forge coverage`), Solidity-coverage |
151
+ | Gas Profiling | Foundry gas snapshots, Hardhat gas-reporter |
152
+ | Dependency Audit | `slither-check-upgradeability`, `npm audit` |
153
+
154
+ ## Red Flags in Code Review
155
+
156
+ - [ ] `assembly` blocks without extensive comments
157
+ - [ ] `delegatecall` to untrusted/upgradable targets
158
+ - [ ] `selfdestruct` in production code
159
+ - [ ] Hardcoded addresses (no immutability)
160
+ - [ ] Missing `initializer` on upgradeable contracts
161
+ - [ ] Floating pragma `^0.8.0` (lock to specific)
162
+ - [ ] No tests for error paths / reverts
163
+ - [ ] Centralized admin with no timelock
164
+ - [ ] Oracle without manipulation resistance
165
+ - [ ] Math without overflow checks (pre-0.8) or precision docs
166
+
167
+ ## When Auditing
168
+
169
+ **Always verify:**
170
+ 1. Does the code match the spec/whitepaper?
171
+ 2. Are all external calls protected against reentrancy?
172
+ 3. Can admin functions be front-run or sandwiched?
173
+ 4. Is there a clear upgrade path with storage safety?
174
+ 5. Are economic invariants formally verified or fuzz-tested?
175
+ 6. Do events enable full off-chain reconstruction?
176
+ 7. Is there an incident response plan (pause, upgrade, rescue)?
177
+
178
+ ---
179
+
180
+ *Use this skill when conducting smart contract audits, reviewing Solidity code for security, designing secure tokenomics, or establishing secure development practices for EVM protocols.*
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: senior-ux-ui-designer
3
+ description: Provides senior-level UX/UI design guidance including design systems, accessibility, user research, interaction design, visual hierarchy, and design-to-development handoff best practices.
4
+ ---
5
+
6
+ # Senior UX/UI Designer Skill
7
+
8
+ You are a senior UX/UI designer with expertise in creating intuitive, accessible, and beautiful digital products. Apply these principles when reviewing designs, creating design systems, or collaborating with engineering.
9
+
10
+ ## Core Principles
11
+
12
+ ### User-Centered Design
13
+ - **Research first**: Understand user needs, mental models, and pain points before designing
14
+ - **Jobs-to-be-done**: Frame features around user outcomes, not features
15
+ - **Progressive disclosure**: Show complexity only when needed
16
+ - **Error prevention**: Design to prevent errors, not just handle them gracefully
17
+
18
+ ### Accessibility (WCAG 2.1 AA minimum)
19
+ - **Color**: 4.5:1 contrast ratio for text, 3:1 for UI components — never rely on color alone
20
+ - **Keyboard**: All interactive elements reachable and operable via keyboard
21
+ - **Focus**: Visible focus indicators, logical tab order, skip links
22
+ - **Screen readers**: Semantic HTML, ARIA labels, live regions for dynamic content
23
+ - **Motion**: Respect `prefers-reduced-motion`, avoid flashing content
24
+
25
+ ### Visual Hierarchy & Layout
26
+ - **Spacing system**: Consistent 4px/8px base unit, scale with purpose
27
+ - **Typography**: Max 2 font families, clear scale (display → heading → body → caption)
28
+ - **Color**: Semantic color tokens (primary, semantic, neutral), not hardcoded values
29
+ - **Grid**: 8pt or 4pt baseline grid, responsive breakpoints defined
30
+
31
+ ## Design System Governance
32
+
33
+ ### Tokens over Values
34
+ ```json
35
+ // ❌ Hardcoded
36
+ { "color": "#3B82F6", "spacing": "16px" }
37
+
38
+ // ✅ Semantic tokens
39
+ { "color": "color-primary-500", "spacing": "space-4" }
40
+ ```
41
+
42
+ ### Component Architecture
43
+ | Level | Purpose | Example |
44
+ |-------|---------|---------|
45
+ | **Tokens** | Raw values | `color-blue-500`, `space-4` |
46
+ | **Primitives** | Unstyled building blocks | `Box`, `Flex`, `Text` |
47
+ | **Components** | Styled, opinionated UI | `Button`, `Card`, `Select` |
48
+ | **Patterns** | Multi-component flows | `Form`, `Wizard`, `Table` |
49
+
50
+ ### Versioning & Updates
51
+ - **Semantic versioning** for design system packages
52
+ - **Deprecation policy**: 2 major versions before removal
53
+ - **Migration guides** for breaking changes
54
+ - **Visual regression testing** in CI (Chromatic, Percy)
55
+
56
+ ## Interaction Design
57
+
58
+ ### Micro-interactions
59
+ - **Duration**: 150-300ms for most transitions
60
+ - **Easing**: `ease-out` for entrances, `ease-in` for exits
61
+ - **Feedback**: Immediate visual response (<100ms) for all interactions
62
+ - **Loading states**: Skeleton screens > spinners for perceived performance
63
+
64
+ ### Motion Guidelines
65
+ | Context | Duration | Easing |
66
+ |---------|----------|--------|
67
+ | Button press | 100ms | ease-out |
68
+ | Modal/drawer | 200-300ms | ease-out |
69
+ | Page transition | 300-400ms | ease-in-out |
70
+ | Tooltip | 150ms | ease-out |
71
+
72
+ ## Design-to-Development Handoff
73
+
74
+ ### Required Deliverables
75
+ 1. **Figma file** with:
76
+ - Organized pages (Exploration → Design System → Flows → Screens)
77
+ - Components with variants, auto-layout, constraints
78
+ - Design tokens published as library
79
+ - Annotated flows with edge cases
80
+ 2. **Specs**: Spacing, typography, colors, shadows as tokens
81
+ 3. **Interaction specs**: States (hover, focus, active, disabled), transitions
82
+ 4. **Responsive behavior**: Breakpoints, fluid scaling, component adaptations
83
+ 5. **Accessibility annotations**: Focus order, ARIA labels, heading structure
84
+
85
+ ### Collaboration Rituals
86
+ - **Design review**: Weekly sync with engineering on upcoming work
87
+ - **Pre-implementation walkthrough**: 15-min async or sync before dev starts
88
+ - **QA design review**: Designer validates implemented UI before merge
89
+ - **Retro**: Monthly sync on design system health, debt, adoption
90
+
91
+ ## Common Design Anti-patterns
92
+
93
+ | Anti-pattern | Better Approach |
94
+ |-------------|-----------------|
95
+ | Designing only happy path | Include empty, error, loading, partial states |
96
+ | Pixel-perfect mockups only | Design for fluid/responsive from start |
97
+ | Custom components for everything | Audit existing design system first |
98
+ | Handoff as "throw over wall" | Co-create with engineers throughout |
99
+ | Ignoring platform conventions | Follow iOS/Android/Web patterns appropriately |
100
+
101
+ ## Design Quality Checklist
102
+
103
+ Before handing off:
104
+ - [ ] All states designed (default, hover, focus, active, disabled, loading, error)
105
+ - [ ] Responsive behavior defined for all breakpoints
106
+ - [ ] Accessibility annotations complete
107
+ - [ ] Content guidelines for dynamic text (truncation, wrapping, max lines)
108
+ - [ ] Asset exports organized (SVG for icons, WebP/AVIF for images)
109
+ - [ ] Design tokens match implemented code values
110
+ - [ ] Component variants documented with usage guidelines
111
+
112
+ ## Recommended Tooling
113
+ - **Design**: Figma (variables, auto-layout, component properties)
114
+ - **Prototyping**: Figma prototype + Principle/Rive for complex motion
115
+ - **Design tokens**: Style Dictionary, Tokens Studio, or Figma Variables
116
+ - **Documentation**: Zeroheight, Storybook, or Notion + Figma embeds
117
+ - **Handoff**: Figma DevMode, Zeplin, or direct Figma inspection
118
+
119
+ ---
120
+
121
+ *Use this skill when you need senior-level design review, design system guidance, accessibility auditing, or design-to-development collaboration patterns.*
package/AGENTS.md CHANGED
@@ -1,8 +1,7 @@
1
1
  # agents-config
2
2
 
3
3
  A shared configuration repository for AI coding agents. Defines how
4
- `.claude/` (Claude Code) and `.opencode/` (opencode) are organized and how
5
- they reference each other.
4
+ `.claude/` (Claude Code) and `.opencode/` (opencode) are organized and how they reference each other.
6
5
 
7
6
  ## Behavior
8
7
 
@@ -15,13 +14,72 @@ Instructions:
15
14
  - Distinguish clearly between facts, estimates, assumptions, and opinions.
16
15
  - If you are unsure, say what is uncertain and why.
17
16
  - Do not invent citations, quotes, studies, URLs, or sources.
18
- - When discussing recent events or rapidly changing topics, indicate that
19
- information may have changed and recommend verification from current
20
- sources.
21
- - When providing statistics, identify whether they are exact figures,
22
- estimates, or approximations.
23
- - If multiple interpretations are possible, explain the alternatives rather
24
- than assuming one is correct.
17
+ - When discussing recent events or rapidly changing topics, indicate that information may have changed and recommend
18
+ verification from current sources.
19
+ - When providing statistics, identify whether they are exact figures, estimates, or approximations.
20
+ - If multiple interpretations are possible, explain the alternatives rather than assuming one is correct.
21
+
22
+ ## Audit Rule
23
+
24
+ When the current task involves significant code changes — for example, after the first code-generation prompt or after
25
+ substantial deviations from the agreed Statement of Work (SOW) — the agent MUST run a system audit before finalizing the
26
+ output.
27
+
28
+ 1. **Pick the right auditor skill** for the domain of the change. Examples (replace `xxx` with the actual domain):
29
+ - Smart contracts / EVM → `senior-solidity-auditor`
30
+ - Bitcoin / Taproot / PSBT → `senior-bitcoin-auditor`
31
+ - Quality assurance / test strategy → `senior-qa`
32
+ - General architecture / system design → `senior-software-architect`
33
+ 2. **Run the audit via the matching `xxx-auditor` skill.** Surface findings, severity, and concrete remediation steps.
34
+ 3. **If the required skill does not exist locally, create it first:**
35
+ - Add `.opencode/skill/<xxx-auditor>/SKILL.md`
36
+ - Mirror to `.claude/skills/<xxx-auditor>/SKILL.md` when a Claude Code counterpart is maintained
37
+ - Register the skill path in `opencode.json` if needed
38
+ - Then execute the audit using the newly created skill.
39
+
40
+ Do not skip the audit because a skill is missing; create the skill and perform the audit as part of the same session.
41
+
42
+ ## AI-Driven SDLC Regulatory Framework
43
+
44
+ This repo ships a BMad-style, subagent-based SDLC that operationalizes the AI-Driven Software Development Lifecycle (now
45
+ fully absorbed into the `sdlc-regulatory` skill). It is **always-on** via the `sdlc-gates` rule and is the default flow
46
+ for any feature/change that touches multiple modules or is medium/high risk.
47
+
48
+ ### Components
49
+
50
+ | Component | Path (opencode) | Claude mirror | Agent Skills mirror |
51
+ |-----------------------|--------------------------------------------------------------------------------------|------------------------------------------------|-------------------------------------------|
52
+ | Methodology skill | `.opencode/skill/sdlc-regulatory/SKILL.md` | `.claude/skills/sdlc-regulatory/SKILL.md` | `.agents/skills/sdlc-regulatory/SKILL.md` |
53
+ | Always-on rule | `.claude/rules/sdlc-gates.md` (also in `opencode.json` instructions) | same | `.agents/rules/sdlc-gates.md` |
54
+ | Orchestrator subagent | `.opencode/agent/sdlc-orchestrator.md` | `.claude/agents/sdlc-orchestrator.md` | `.agents/agents/sdlc-orchestrator.md` |
55
+ | Role subagents (×9) | `.opencode/agent/sdlc-{analyst,pm,architect,sm,dev,qa,security,reviewer,auditor}.md` | mirrored (Claude Code frontmatter, no `mode:`) | mirrored verbatim |
56
+ | `/sdlc` slash command | `.opencode/command/sdlc.md` | `.claude/commands/sdlc.md` | `.agents/commands/sdlc.md` |
57
+
58
+ ### SDLC chain
59
+
60
+ ```
61
+ requirement → sdlc-analyst → sdlc-pm → sdlc-architect → sdlc-sm
62
+ → sdlc-dev → sdlc-qa → sdlc-security → sdlc-reviewer → sdlc-auditor
63
+ → deploy (CI/CD, subject to the Deployment Gate)
64
+ ```
65
+
66
+ Each role owns one gate from the `sdlc-regulatory` skill. A failed gate returns work to the previous role with a
67
+ `BLOCKED` note; no gate is skipped. AI never self-validates its own work — reviewer/auditor/security are different
68
+ agents from dev. High-risk changes require explicit human approval at Architecture, Security, and Code Review gates. The
69
+ `sdlc-regulatory` skill also contains a compliance crosswalk (EU AI Act, NIST AI RMF, ISO/IEC 42001, SOC 2, GDPR) for
70
+ regulated projects.
71
+
72
+ ### When to use
73
+
74
+ - **Full `/sdlc` flow**: any change touching multiple modules, medium/high risk, or requiring traceability/compliance
75
+ artifacts.
76
+ - **Inline (main agent only)**: documentation, test generation, trivial internal refactoring (autonomy 80–100%). Still
77
+ subject to the `sdlc-gates` rule.
78
+ - **Above ~50% autonomy cap**: must use the full flow with human approvals.
79
+
80
+ See the `sdlc-regulatory` skill for the full gate checklists, risk-autonomy table, traceability format, and the
81
+ compliance crosswalk. Config is loaded once at startup — restart opencode after editing `opencode.json`, agents, skills,
82
+ plugins, or commands.
25
83
 
26
84
  ## Layout
27
85
 
@@ -33,6 +91,11 @@ agents-config/
33
91
  ├── docs/ # Project documentation
34
92
  ├── research/ # Research and investigation materials
35
93
  ├── resources/ # Project resources and assets
94
+ ├── .agents/ # Cross-client agent config (agentskills.io compatible)
95
+ │ ├── skills/ # Skill folders, each with SKILL.md
96
+ │ ├── agents/ # Subagents
97
+ │ ├── commands/ # Slash commands
98
+ │ └── rules/ # Always-loaded rule files
36
99
  ├── .claude/ # Claude Code project config
37
100
  │ ├── CLAUDE.md # Claude Code instructions (sources AGENTS.md)
38
101
  │ ├── CLAUDE.local.md # Personal overrides (gitignored)
@@ -64,30 +127,33 @@ agents-config/
64
127
 
65
128
  ## Linking
66
129
 
67
- - `AGENTS.md` (root) is the single source of truth for layout and conventions.
68
- Both tools read it: Claude Code via `.claude/CLAUDE.md`, opencode via
130
+ - `AGENTS.md` (root) is the single source of truth for layout and conventions. Both tools read it: Claude Code via
131
+ `.claude/CLAUDE.md`, opencode via
69
132
  `opencode.json` → `instructions` → `AGENTS.md`.
70
133
  - `.opencode/AGENTS.md` is opencode-specific instructions (loaded by
71
- `opencode.json`). It defers to the root `AGENTS.md` for shared structure
72
- and only adds opencode-only notes.
73
- - `.claude/CLAUDE.md` is Claude Code's instructions file. It sources the
74
- root `AGENTS.md` so both tools see the same layout.
75
- - Skills live in `.opencode/skill/` (or `.opencode/skills/`) and
76
- `.claude/skills/`. `opencode.json` declares both paths under
77
- `skills.paths` so opencode auto-discovers the Claude-format skills.
134
+ `opencode.json`). It defers to the root `AGENTS.md` for shared structure and only adds opencode-only notes.
135
+ - `.claude/CLAUDE.md` is Claude Code's instructions file. It sources the root `AGENTS.md` so both tools see the same
136
+ layout.
137
+ - `.agents/` is the cross-client configuration directory compatible with the
138
+ [Agent Skills](https://agentskills.io/) convention. It is optional; existing
139
+ `.claude/` and `.opencode/` directories remain authoritative for their respective clients. The `.agents/` directory is
140
+ intended as a shared fallback so skills registered there are visible to any agent that scans the
141
+ `.agents/skills/` convention.
142
+ - Skills live in `.opencode/skill/` (or `.opencode/skills/`), `.claude/skills/`, and `.agents/skills/`. `opencode.json`
143
+ declares all three paths under
144
+ `skills.paths` so opencode auto-discovers both Claude-format and Agent-Skills skills.
78
145
  - The example `docs` subagent exists in both `.opencode/agent/docs.md` and
79
- `.claude/agents/docs.md`. Each tool uses its own copy; they share the same
80
- description so behavior is consistent.
146
+ `.claude/agents/docs.md`. Each tool uses its own copy; they share the same description so behavior is consistent.
81
147
 
82
148
  ## Adding a new component
83
149
 
84
- | Component | opencode path | Claude Code path |
85
- | --------------- | ------------------------- | -------------------------- |
86
- | Subagent | `.opencode/agent/<n>.md` | `.claude/agents/<n>.md` |
87
- | Skill | `.opencode/skill/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` |
88
- | Slash command | `.opencode/command/<n>.md` | `.claude/commands/<n>.md` |
89
- | Plugin | `.opencode/plugin/<n>.ts` | n/a |
90
- | Always-on rule | add to `opencode.json` `instructions` | add to `.claude/rules/` |
150
+ | Component | opencode path | Claude Code path | Agent Skills path |
151
+ |----------------|---------------------------------------|-------------------------------|-------------------------------|
152
+ | Subagent | `.opencode/agent/<n>.md` | `.claude/agents/<n>.md` | `.agents/agents/<n>.md` |
153
+ | Skill | `.opencode/skill/<n>/SKILL.md` | `.claude/skills/<n>/SKILL.md` | `.agents/skills/<n>/SKILL.md` |
154
+ | Slash command | `.opencode/command/<n>.md` | `.claude/commands/<n>.md` | `.agents/commands/<n>.md` |
155
+ | Plugin | `.opencode/plugin/<n>.ts` | n/a | n/a |
156
+ | Always-on rule | add to `opencode.json` `instructions` | add to `.claude/rules/` | add to `.agents/rules/` |
91
157
 
92
158
  ## Code Generation Pipeline
93
159
 
@@ -108,9 +174,9 @@ To create an agent for code generation tasks:
108
174
  ```
109
175
 
110
176
  2. **Create supporting rules** in `.claude/rules/code-generation.md`:
111
- - Coding standards and patterns
112
- - Language-specific guidelines
113
- - Testing requirements
177
+ - Coding standards and patterns
178
+ - Language-specific guidelines
179
+ - Testing requirements
114
180
 
115
181
  3. **Add skills** in `.opencode/skill/code-gen/SKILL.md`:
116
182
  ```markdown
@@ -147,22 +213,25 @@ To create an agent for code generation tasks:
147
213
  }
148
214
  ```
149
215
 
150
- After editing `opencode.json`, an agent file, a skill, a plugin, or any
151
- other config-time file, restart opencode — config is loaded once on startup
152
- and is not hot-reloaded.
216
+ After editing `opencode.json`, an agent file, a skill, a plugin, or any other config-time file, restart opencode —
217
+ config is loaded once on startup and is not hot-reloaded.
153
218
 
154
219
  ## General Recommendations
155
220
 
156
221
  - Create a `README.md` file with deployment instructions
157
222
  - Create a `.aiignore` file to exclude files and directories from AI analysis
158
223
  - Store R&D artifacts in the `docs/` directory:
159
- - `docs/BUSINESS_LOGIC.md` - Business requirements and logic
160
- - `docs/IMPLEMENTATION.md` - Implementation plan, status, and progress
161
- - `docs/ARCHITECTURE.md` - Technical approaches, stack decisions, and architecture
224
+ - `docs/BUSINESS_LOGIC.md` - Business requirements and logic
225
+ - `docs/IMPLEMENTATION.md` - Implementation plan, status, and progress
226
+ - `docs/adr/NNNN-<slug>.md` - Architecture Decision Records
227
+
228
+ The AI-Readable Codebase contract in the `sdlc-regulatory` skill also requires root-level `ARCHITECTURE.md`,
229
+ `CONTRIBUTING.md`, and `SECURITY.md` files for any project the SDLC runs against. This repo maintains all of them.
162
230
 
163
231
  ## Architecture Approach Selection
164
232
 
165
- Before implementation, always ask the user what architecture approach to use, as the choice depends on business logic complexity. Consider these patterns:
233
+ Before implementation, always ask the user what architecture approach to use, as the choice depends on business logic
234
+ complexity. Consider these patterns:
166
235
 
167
236
  - **Clean Architecture** - Separates business logic from frameworks and I/O, promoting testability and maintainability
168
237
  - **Onion Architecture** - Layers of dependencies pointing inward toward the domain core, emphasizing domain isolation
@@ -172,25 +241,33 @@ Before implementation, always ask the user what architecture approach to use, as
172
241
  - **Microservices** - Decomposes application into loosely coupled, independently deployable services
173
242
  - **Monolithic** - Single deployable unit containing all functionality, suitable for simpler applications
174
243
 
175
- Choose the approach based on project scope, team size, scalability requirements, and business logic complexity. Document the decision in `docs/ARCHITECTURE.md`.
244
+ Choose the approach based on project scope, team size, scalability requirements, and business logic complexity. Document
245
+ the decision in an ADR under `docs/adr/` and summarize it in root `ARCHITECTURE.md`.
176
246
 
177
247
  ## Security Guidelines
178
248
 
179
249
  - Set up a vault (e.g., Hardhat vault) on your machine or repository to securely store private keys
180
250
  - Never commit sensitive information directly to the repository
181
251
  - Use environment variables or secure vault solutions for all secrets
182
- - **LLM Security Rule**: LLMs must never commit tokens, keys, personal data, or any sensitive information to code, even if they have permission to read such data. This prevents accidental data breaches and maintains security boundaries.
252
+ - **LLM Security Rule**: LLMs must never commit tokens, keys, personal data, or any sensitive information to code, even
253
+ if they have permission to read such data. This prevents accidental data breaches and maintains security boundaries.
183
254
 
184
255
  ## Cross-Platform Portability
185
256
 
186
257
  To make the project portable across Node.js, Python, and Rust infrastructures:
187
258
 
188
- - **Language-Agnostic Configuration**: Store environment-specific settings in `.env` files or external configuration management systems
189
- - **Containerization**: Use Docker and docker-compose to package applications and their dependencies for consistent deployment across platforms
190
- - **API-First Design**: Expose functionality through REST/gRPC APIs to enable interoperability between services written in different languages
191
- - **Shared Libraries**: Implement core business logic in portable formats (e.g., Protocol Buffers, JSON Schema) that can be consumed by all target platforms
192
- - **Infrastructure as Code**: Use tools like Terraform or CloudFormation to define infrastructure that can deploy any of the language-specific services
193
- - **Polyglot Persistence**: Design data access patterns that work across different database clients and ORMs for each platform
259
+ - **Language-Agnostic Configuration**: Store environment-specific settings in `.env` files or external configuration
260
+ management systems
261
+ - **Containerization**: Use Docker and docker-compose to package applications and their dependencies for consistent
262
+ deployment across platforms
263
+ - **API-First Design**: Expose functionality through REST/gRPC APIs to enable interoperability between services written
264
+ in different languages
265
+ - **Shared Libraries**: Implement core business logic in portable formats (e.g., Protocol Buffers, JSON Schema) that can
266
+ be consumed by all target platforms
267
+ - **Infrastructure as Code**: Use tools like Terraform or CloudFormation to define infrastructure that can deploy any of
268
+ the language-specific services
269
+ - **Polyglot Persistence**: Design data access patterns that work across different database clients and ORMs for each
270
+ platform
194
271
 
195
272
  ## AI Pipeline Configuration
196
273
 
@@ -210,57 +287,80 @@ All generated code must meet production-ready standards:
210
287
  - **Deep Research First** - Conduct thorough research at the beginning of development
211
288
  - **Document Findings** - Store research results and technical decisions
212
289
  - **Time Estimates** - Provide estimates in hours and weeks for all development work
213
- - **Comprehensive Testing** -
214
- - Local and development environment testing required
215
- - Minimum 80% code coverage
216
- - Include unit tests, integration tests, and end-to-end tests
217
- - Automated test execution as part of the development workflow
290
+ - **Comprehensive Testing** -
291
+ - Local and development environment testing required
292
+ - Minimum 80% code coverage
293
+ - Include unit tests, integration tests, and end-to-end tests
294
+ - Automated test execution as part of the development workflow
218
295
 
219
296
  ## Expert Agent Personalities
220
297
 
221
298
  Create specialized AI agents with senior-level expertise in key domains:
222
299
 
223
300
  - **Senior Software Architect** - Deep knowledge in:
224
- - Web architecture and scalable systems design
225
- - Mobile app architecture (iOS/Android)
226
- - Embedded systems and IoT applications
227
- - Cloud infrastructure and microservices
228
- - Database design and optimization
229
- - Security architecture and compliance
301
+ - Web architecture and scalable systems design
302
+ - Mobile app architecture (iOS/Android)
303
+ - Embedded systems and IoT applications
304
+ - Cloud infrastructure and microservices
305
+ - Database design and optimization
306
+ - Security architecture and compliance
230
307
 
231
308
  - **Senior Software Developer** - Comprehensive skills across:
232
- - Frontend development (React, Vue, Angular, etc.)
233
- - Backend development (Node.js, Python, Java, Go, etc.)
234
- - Mobile development (React Native, Flutter, native iOS/Android)
235
- - Embedded programming (C/C++, Rust, Arduino, etc.)
236
- - Database technologies (SQL, NoSQL, GraphQL)
237
- - DevOps and CI/CD pipelines
238
- - Testing frameworks and methodologies
309
+ - Frontend development (React, Vue, Angular, etc.)
310
+ - Backend development (Node.js, Python, Java, Go, etc.)
311
+ - Mobile development (React Native, Flutter, native iOS/Android)
312
+ - Embedded programming (C/C++, Rust, Arduino, etc.)
313
+ - Database technologies (SQL, NoSQL, GraphQL)
314
+ - DevOps and CI/CD pipelines
315
+ - Testing frameworks and methodologies
239
316
 
240
317
  - **DevOps Engineer** - Expertise in:
241
- - Infrastructure as Code (Terraform, CloudFormation)
242
- - Containerization and orchestration (Docker, Kubernetes)
243
- - CI/CD pipeline design and implementation
244
- - Cloud platforms (AWS, Azure, GCP)
245
- - Monitoring and logging solutions
246
- - System performance optimization
247
- - Deployment strategies and rollback procedures
318
+ - Infrastructure as Code (Terraform, CloudFormation)
319
+ - Containerization and orchestration (Docker, Kubernetes)
320
+ - CI/CD pipeline design and implementation
321
+ - Cloud platforms (AWS, Azure, GCP)
322
+ - Monitoring and logging solutions
323
+ - System performance optimization
324
+ - Deployment strategies and rollback procedures
248
325
 
249
326
  - **SecOps Specialist** - Specialized security operations knowledge:
250
- - Security monitoring and incident response
251
- - Vulnerability assessment and penetration testing
252
- - Compliance frameworks (SOC 2, ISO 27001, GDPR)
253
- - Threat modeling and risk assessment
254
- - Security tooling and automation
255
- - Secure coding practices and code review
256
- - Identity and access management
327
+ - Security monitoring and incident response
328
+ - Vulnerability assessment and penetration testing
329
+ - Compliance frameworks (SOC 2, ISO 27001, GDPR)
330
+ - Threat modeling and risk assessment
331
+ - Security tooling and automation
332
+ - Secure coding practices and code review
333
+ - Identity and access management
257
334
 
258
335
  - **QA Engineer** - Comprehensive testing expertise:
259
- - Test planning and strategy development
260
- - Manual and automated testing methodologies
261
- - Test case design and execution
262
- - Bug tracking and reporting
263
- - Performance and load testing
264
- - API and integration testing
265
- - Test automation frameworks (Selenium, Cypress, Jest, etc.)
266
- - Continuous testing in CI/CD pipelines
336
+ - Test planning and strategy development
337
+ - Manual and automated testing methodologies
338
+ - Test case design and execution
339
+ - Bug tracking and reporting
340
+ - Performance and load testing
341
+ - API and integration testing
342
+ - Test automation frameworks (Selenium, Cypress, Jest, etc.)
343
+ - Continuous testing in CI/CD pipelines
344
+
345
+ ## Documentation Maintenance
346
+
347
+ At the end of each session or task, review and update relevant documentation:
348
+
349
+ - **AGENTS.md** - Update if new conventions, patterns, or structures were introduced
350
+ - **ARCHITECTURE.md** - Document architecture decisions and changes (root file; per the AI-Readable Codebase contract in
351
+ the `sdlc-regulatory` skill)
352
+ - **docs/BUSINESS_LOGIC.md** - Record new business requirements or logic changes
353
+ - **docs/IMPLEMENTATION.md** - Track implementation progress and status
354
+ - **README.md** - Update setup, deployment, or usage instructions if changed
355
+ - **Code comments** - Add or update JSDoc/TSDoc for new public APIs
356
+
357
+ ### Documentation Checklist (End of Session)
358
+
359
+ - [ ] New files/directories documented in appropriate README or STRUCTURE.md
360
+ - [ ] Architecture decisions recorded in ADRs or ARCHITECTURE.md
361
+ - [ ] API changes reflected in documentation
362
+ - [ ] Configuration changes documented
363
+ - [ ] Testing strategy updated if new test patterns introduced
364
+ - [ ] Dependencies added/removed documented
365
+
366
+ Keep documentation synchronized with code — treat outdated docs as technical debt.