Three Principles for AI-Driven Development
SDD (Skill-Driven Development) CLI Tool - One-click initialization for Trinity Workflow v2 configuration.
┌─────────────────────────────────────────────────────────────────────────┐
│ AI-Driven Development Three Principles │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Attention is All You Need │
│ ───────────────────────── │
│ Focus AI on the right information, not淹没 in irrelevant code │
│ → Skills system precisely controls AI's attention scope │
│ → Load only necessary context, avoid token waste │
│ │
│ 2. Context is All You Need │
│ ──────────────────────── │
│ Persistent context = Agent's "working memory" │
│ → planning-with-files as context anchor │
│ → task_plan.md / findings.md / progress.md / delta-log.md │
│ → Agent always knows: Where? What done? Why? Next? │
│ │
│ 3. System Agent Flow is All You Need │
│ ──────────────────────────────── │
│ Structured agent collaboration flow, not random interactions │
│ → Three-phase: planning-with-files → OpenSpec CLI → planning-with-files│
│ → 3-Strike Protocol: Auto error handling, reduce manual intervention │
│ → Profile Mode: Quick / Core / Expanded adaptive complexity │
│ │
└─────────────────────────────────────────────────────────────────────────┘
| Problem | Traditional Approach | Trinity Approach |
|---|---|---|
| AI doesn't know current state | Re-explain every time | Read task_plan.md |
| AI forgets previous decisions | Repeat discussions | Read findings.md |
| AI doesn't know next step | Manual user guidance | Schema-driven flow |
| Error handling chaos | Random retries | 3-Strike Protocol |
| Context loss | Lost when session ends | File persistence |
Trinity Skills supports multiple AI coding assistants:
| Platform | Skills Directory | Status |
|---|---|---|
| Claude Code | .claude/skills/ |
✅ Supported |
| OpenCode | .opencode/skills/ |
✅ Supported |
| Codex | .codex/skills/ |
✅ Supported |
| Cursor | .cursor/skills/ |
🚧 Planned |
Trinity Workflow depends on the following skills, please install first:
Implementation of "Context is All You Need" - Tracking file management as Agent context anchor.
# Claude Code
git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files
# OpenCode
git clone https://github.com/OthmanAdi/planning-with-files ~/.opencode/skills/planning-with-files
# Codex
git clone https://github.com/OthmanAdi/planning-with-files ~/.codex/skills/planning-with-filesImplementation of "Attention is All You Need" - Professional development skill set, precise control of AI attention scope.
# Claude Code
git clone https://github.com/obra/superpowers ~/.claude/skills/superpowers
# OpenCode
git clone https://github.com/obra/superpowers ~/.opencode/skills/superpowers
# Codex
git clone https://github.com/obra/superpowers ~/.codex/skills/superpowers# Using npx (recommended)
npx sdd-ql-workflow init
# Or install globally
npm install -g sdd-ql-workflow
sdd init# Execute in project root (auto-detect platform)
npx sdd-ql-workflow init
# Specify platform
npx sdd-ql-workflow init --platform claude
npx sdd-ql-workflow init --platform opencode
npx sdd-ql-workflow init --platform codex
npx sdd-ql-workflow init --platform all
# After initialization, available commands:
# /trinity:new "description" - Create new change (with tracking)
# /trinity:continue - Continue next artifact
# /trinity:apply - Execute tasks
# /trinity:verify - Verify implementation
# /trinity:archive - Archive change
# /trinity:ff "description" - Fast-forward flowImplementation of "System Agent Flow is All You Need" - Structured agent collaboration flow:
┌─────────────────────────────────────────────────────────────────────────┐
│ Trinity Three-Phase Architecture │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ User calls: /trinity:new "feature-x" │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Phase 1: Call planning-with-files skill │ │
│ │ - Read/initialize tracking files (Context) │ │
│ │ - task_plan.md, findings.md, progress.md │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Phase 2: Execute OpenSpec CLI │ │
│ │ - openspec new change --schema trinity-workflow-v2 │ │
│ │ - openspec status --json │ │
│ │ - openspec instructions --json │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Phase 3: Call planning-with-files skill │ │
│ │ - Update tracking files (based on CLI response) │ │
│ │ - Log operations, progress, decisions │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ planning-with-files = Agent Context Anchor │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Tracking files location: openspec/changes/{change-id}/ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ task_plan.md ←── Current phase, goals, task list │ │
│ │ findings.md ←── Technical findings, ADR │ │
│ │ progress.md ←── Session progress log │ │
│ │ delta-log.md ←── Delta Specs change records │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Agent always knows: │
│ • Which phase am I in? │
│ • Which files have been modified? │
│ • Why were they modified? │
│ • What's next? │
│ │
└─────────────────────────────────────────────────────────────────────────┘
| Mode | Use Case | Artifacts | Description |
|---|---|---|---|
| Quick | Single file edit, Bug Fix | proposal → tasks → apply | Skip specs/design |
| Core | New features, Multi-file changes | proposal → specs → design → tasks → apply | Standard flow |
| Expanded | Complex features, Cross-module, Architecture refactor | Full flow + verify | Includes verification |
┌─────────────────────────────────────────────────────────────────────────┐
│ 3-Strike Protocol │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Attempt 1: Diagnose & Fix → Log to progress.md │
│ ↓ Failed │
│ Attempt 2: Try Alternative → Log to findings.md │
│ ↓ Failed │
│ Attempt 3: Rethink Problem → Log to findings.md │
│ ↓ Failed │
│ Escalate to User → Update task_plan.md [BLOCKED] │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Initialize SDD workflow configuration:
npx sdd-ql-workflow init [options]
Options:
-f, --force Overwrite existing files
--skip-commands Skip command file copying
--skip-schema Skip schema file copying
--skip-skills Skip skill file copying
--platform <name> Target platform: claude | opencode | codex | both | all (default: auto-detect)List available commands and schemas:
npx sdd-ql-workflow list| Command | Description |
|---|---|
/trinity:new "description" |
Create new change (with tracking) |
/trinity:continue |
Continue next artifact |
/trinity:apply |
Execute tasks (with 3-Strike) |
/trinity:verify |
Verify implementation (3 dimensions) |
/trinity:archive |
Archive change (generate summary) |
/trinity:ff "description" |
Fast-forward flow (one-click create) |
your-project/
├── openspec/
│ ├── config.yaml
│ ├── project.md
│ ├── .active
│ ├── schemas/trinity-workflow-v2/
│ ├── specs/
│ └── changes/
│ └── {change-id}/
│ ├── task_plan.md # Phase progress
│ ├── findings.md # Technical findings
│ ├── progress.md # Operation log
│ ├── delta-log.md # Spec changes
│ ├── proposal.md
│ ├── specs/
│ ├── design.md
│ └── tasks.md
└── .claude/
└── skills/
├── trinity-new/SKILL.md
├── trinity-continue/SKILL.md
├── trinity-apply/SKILL.md
├── trinity-verify/SKILL.md
├── trinity-archive/SKILL.md
├── trinity-ff/SKILL.md
└── trinity-workflow/templates/
your-project/
├── openspec/
│ └── ...
└── .opencode/
├── commands/
│ ├── sdd-*.md
│ └── hybrid-*.md
└── skills/
└── trinity-*/
your-project/
├── openspec/
│ └── ...
└── .codex/
└── skills/
└── trinity-*/
| Schema | Description |
|---|---|
trinity-workflow-v2 |
Trinity Architecture Workflow v2 |
- Skills stored in
.claude/skills/directory - Uses
SKILL.mdfile format - Supports native slash commands
- Skills stored in
.opencode/skills/directory - Commands stored in
.opencode/commands/directory - Requires oh-my-opencode plugin
- Skills stored in
.codex/skills/directory - Uses
SKILL.mdfile format - Trigger Trinity skills with natural language, for example: "use trinity-new to create feature-x"
# Install dependencies
cd sdd-cli
npm install
# Local testing
node bin/cli.js init
node bin/cli.js list-
Add Worktrunk config (wt.toml)
-
Pre-switch: sync OpenSpec specs from origin/main
-
Pre-merge: run tests and merging
-
Post-switch: hint for start Agent
-
post-merge: notify when merge complete
-
copy wt.toml to
.config/directory -
Update CLI to copy wt.toml
-
Update version history
- Fix: Correct archive path from
openspec/changes/archive/toopenspec/archive/
- Fix: Add missing artifact templates for trinity-workflow-v2 schema
- Publish to GitHub and npm
- Add Three Principles for AI-Driven Development
- Update README with core philosophy
- Add English documentation
- Fix brainstorming skill reference (superpowers/brainstorming)
- Add prerequisite skills installation guide
- Clarify tracking files location (openspec/changes/{change-id}/)
- Remove .trinity directory creation logic
- Three-phase architecture: planning-with-files → OpenSpec CLI → planning-with-files
- Every operation updates tracking files via planning-with-files
- Add Trinity Workflow v2 schema
- Integrate Planning-with-Files as context anchor
- Support Delta Specs mechanism
- Profile mode auto-selection
- 3-Strike Protocol integration
- Multi-platform support: Claude Code + OpenCode + Codex
- Initial version
- Trinity Workflow v1
- Hybrid Workflow support
MIT