From 2d25d5e4f7b27687d4963cca66d449570eb9a74b Mon Sep 17 00:00:00 2001 From: Cody Fincher Date: Sun, 26 Apr 2026 22:42:23 +0000 Subject: [PATCH 1/3] fix(flow): align host agents and beads setup --- .agents/plugins/marketplace.json | 2 +- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 3 +- .codex-plugin/plugin.json | 23 ++++ .codex/INSTALL.md | 4 +- .codex/agents/code-reviewer.toml | 8 ++ .codex/agents/executor.toml | 8 ++ .codex/agents/plan-generator.toml | 8 ++ .codex/agents/prd-orchestrator.toml | 8 ++ .cursor-plugin/plugin.json | 16 --- .cursor/rules/flow.mdc | 8 ++ .github/agents/code-reviewer.agent.md | 6 + .github/agents/executor.agent.md | 6 + .github/agents/plan-generator.agent.md | 6 + .github/agents/prd-orchestrator.agent.md | 6 + .opencode/INSTALL.md | 4 +- .opencode/agents/code-reviewer.md | 13 ++ .opencode/agents/executor.md | 15 +++ .opencode/agents/plan-generator.md | 15 +++ .opencode/agents/prd-orchestrator.md | 15 +++ AGENTS.md | 71 +++++++--- Makefile | 9 +- README.md | 77 +++++++++-- agents/code-reviewer.md | 22 ++++ agents/executor.md | 16 +-- agents/plan-generator.md | 18 +-- agents/prd-orchestrator.md | 18 +-- commands/flow-finish.md | 2 +- commands/flow-implement.md | 6 +- commands/flow-plan.md | 4 +- commands/flow-prd.md | 4 +- commands/flow-refine.md | 6 +- commands/flow-revert.md | 2 +- commands/flow-revise.md | 2 +- commands/flow-setup.md | 13 +- commands/flow-sync.md | 9 +- commands/flow/cleanup.toml | 2 +- commands/flow/finish.toml | 2 +- commands/flow/implement.toml | 2 +- commands/flow/plan.toml | 2 +- commands/flow/prd.toml | 2 +- commands/flow/refine.toml | 4 +- commands/flow/refresh.toml | 2 +- commands/flow/revert.toml | 4 +- commands/flow/revise.toml | 4 +- commands/flow/setup.toml | 36 ++++- commands/flow/sync.toml | 8 ++ docs/multi-host-plugin-patterns.md | 55 ++++---- gemini-extension.json | 2 +- hooks/detect-env.ps1 | 5 +- hooks/detect-env.sh | 5 +- package.json | 2 +- pyproject.toml | 9 +- skills/flow/SKILL.md | 23 +++- skills/flow/references/cleanup.md | 2 +- skills/flow/references/finish.md | 2 +- skills/flow/references/implement.md | 2 +- skills/flow/references/refresh.md | 2 +- skills/flow/references/setup.md | 10 +- templates/agent/beads.json | 17 ++- templates/agent/workflow.md | 15 ++- templates/opencode/agents/flow.md | 11 +- templates/opencode/commands/flow-finish.md | 2 +- templates/opencode/commands/flow-implement.md | 2 +- templates/opencode/commands/flow-revert.md | 2 +- templates/opencode/commands/flow-revise.md | 2 +- templates/opencode/commands/flow-setup.md | 13 +- tests/test_beads_policy.py | 64 +++++++++ tests/test_gemini_plan_mode.py | 13 +- tests/test_validate_codex_manifest.py | 30 +++++ tests/test_validate_skills.py | 41 +++++- tools/install.sh | 10 +- tools/validate-codex-manifest.py | 67 ++++++---- tools/validate-skills.py | 123 +++++++++++++++++- uv.lock | 2 +- 75 files changed, 817 insertions(+), 239 deletions(-) create mode 100644 .codex-plugin/plugin.json create mode 100644 .codex/agents/code-reviewer.toml create mode 100644 .codex/agents/executor.toml create mode 100644 .codex/agents/plan-generator.toml create mode 100644 .codex/agents/prd-orchestrator.toml delete mode 100644 .cursor-plugin/plugin.json create mode 100644 .cursor/rules/flow.mdc create mode 100644 .github/agents/code-reviewer.agent.md create mode 100644 .github/agents/executor.agent.md create mode 100644 .github/agents/plan-generator.agent.md create mode 100644 .github/agents/prd-orchestrator.agent.md create mode 100644 .opencode/agents/code-reviewer.md create mode 100644 .opencode/agents/executor.md create mode 100644 .opencode/agents/plan-generator.md create mode 100644 .opencode/agents/prd-orchestrator.md create mode 100644 agents/code-reviewer.md create mode 100644 tests/test_beads_policy.py create mode 100644 tests/test_validate_codex_manifest.py diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index df4fdd0..206422c 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -15,7 +15,7 @@ { "name": "flow", "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration", - "version": "0.20.0", + "version": "0.20.1", "source": { "source": "local", "path": "./plugins/flow" }, "policy": { "installation": "AVAILABLE" }, "category": "Development", diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c6fa145..01de391 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ { "name": "flow", "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration", - "version": "0.20.0", + "version": "0.20.1", "source": "./", "author": { "name": "cofin" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 4d5726a..7d300f3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "flow", "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration", - "version": "0.20.0", + "version": "0.20.1", "author": { "name": "cofin" }, @@ -11,6 +11,7 @@ "keywords": ["flow", "context-driven-development", "beads", "tdd", "ai-agent", "workflow", "spec-first", "skills", "slash-commands", "subagents"], "skills": ["./skills/"], "commands": ["./commands/"], + "agents": ["./agents/"], "hooks": "./hooks/hooks-claude.json", "userConfig": { "useBeads": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..dfd72b9 --- /dev/null +++ b/.codex-plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "flow", + "version": "0.20.1", + "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration", + "author": { "name": "cofin" }, + "homepage": "https://github.com/cofin/flow", + "repository": "https://github.com/cofin/flow", + "license": "MIT", + "keywords": ["flow", "context-driven-development", "beads", "tdd", "ai-agent", "workflow", "spec-first", "skills"], + "skills": "./skills/", + "interface": { + "displayName": "Flow", + "shortDescription": "Context-driven planning, TDD implementation, and Beads-backed memory", + "category": "Development", + "capabilities": ["Read", "Write"], + "defaultPrompt": [ + "Use the Flow skill to set up this project", + "Use the Flow skill to create a PRD for user authentication", + "Use the Flow skill to refine this spec into implementation-ready tasks", + "Use the Flow skill to implement the current flow with TDD and verification" + ] + } +} diff --git a/.codex/INSTALL.md b/.codex/INSTALL.md index 7dcc44f..614268a 100644 --- a/.codex/INSTALL.md +++ b/.codex/INSTALL.md @@ -5,7 +5,7 @@ Flow ships as a native Codex plugin via marketplace. ## Prerequisites - Codex CLI 0.117.0+ (with marketplace support; verify with `codex --version`) -- [Beads CLI](https://github.com/steveyegge/beads) +- [Beads CLI](https://github.com/gastownhall/beads) ## Install @@ -39,6 +39,8 @@ Use Flow to implement the current flow with TDD The Flow skill responds to all `/flow:*` intents (`setup`, `prd`, `plan`, `implement`, `sync`, `status`, `refresh`, `research`, `docs`, etc.). +Repo-local subagents live in `.codex/agents/*.toml`. They are pure TOML, inherit tools from the active Codex session, and do not define a per-agent `tools` allowlist. + ## Recommended Codex settings In `~/.codex/config.toml`, set plan-mode reasoning effort high (Codex has no plugin-author hook for an artifact-directory equivalent to Gemini's `plan.directory`): diff --git a/.codex/agents/code-reviewer.toml b/.codex/agents/code-reviewer.toml new file mode 100644 index 0000000..4c94d62 --- /dev/null +++ b/.codex/agents/code-reviewer.toml @@ -0,0 +1,8 @@ +name = "code-reviewer" +description = "Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification." +nickname_candidates = ["code reviewer", "reviewer"] +developer_instructions = """ +Review like an owner. Prioritize correctness, security, behavior regressions, host integration schema mistakes, missing tests, and missing verification evidence. + +Lead with concrete findings ordered by severity. Include file references and explain the failure mode. If there are no findings, say so and call out remaining test gaps or residual risk. +""" diff --git a/.codex/agents/executor.toml b/.codex/agents/executor.toml new file mode 100644 index 0000000..2b409b8 --- /dev/null +++ b/.codex/agents/executor.toml @@ -0,0 +1,8 @@ +name = "executor" +description = "Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline." +nickname_candidates = ["executor", "flow executor"] +developer_instructions = """ +Execute Flow implementation work from the current spec or Beads task. + +Use Beads as the source of truth. Record investigation findings with bd note, follow Red-Green-Refactor, run the canonical verification commands, and never claim completion without fresh evidence. +""" diff --git a/.codex/agents/plan-generator.toml b/.codex/agents/plan-generator.toml new file mode 100644 index 0000000..f498122 --- /dev/null +++ b/.codex/agents/plan-generator.toml @@ -0,0 +1,8 @@ +name = "plan-generator" +description = "Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis." +nickname_candidates = ["planner", "plan generator"] +developer_instructions = """ +Create Flow planning worksheets that a low-context implementer can execute correctly on the first pass. + +Read the relevant code first, identify exact files and commands, write concrete TDD tasks, and route unclear requirements back into refinement instead of hand-waving. +""" diff --git a/.codex/agents/prd-orchestrator.toml b/.codex/agents/prd-orchestrator.toml new file mode 100644 index 0000000..897a6dd --- /dev/null +++ b/.codex/agents/prd-orchestrator.toml @@ -0,0 +1,8 @@ +name = "prd-orchestrator" +description = "Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows." +nickname_candidates = ["orchestrator", "prd orchestrator"] +developer_instructions = """ +Turn broad goals into Flow PRD roadmaps. + +Complete research up front, split work into coherent child flows, preserve decisions in Beads notes, and validate the roadmap with code-reviewer before presenting it as ready. +""" diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json deleted file mode 100644 index 4eb7505..0000000 --- a/.cursor-plugin/plugin.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "flow", - "displayName": "Flow", - "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration", - "version": "0.20.0", - "author": { - "name": "cofin" - }, - "homepage": "https://github.com/cofin/flow", - "repository": "https://github.com/cofin/flow", - "license": "MIT", - "keywords": ["flow", "context-driven-development", "beads", "tdd", "ai-agent", "workflow"], - "skills": "./skills/", - "commands": "./commands/", - "hooks": "./hooks/hooks-cursor.json" -} diff --git a/.cursor/rules/flow.mdc b/.cursor/rules/flow.mdc new file mode 100644 index 0000000..e8be117 --- /dev/null +++ b/.cursor/rules/flow.mdc @@ -0,0 +1,8 @@ +--- +description: Use Flow for context-driven development workflows in repositories with .agents context. +alwaysApply: true +--- + +When a repository has `.agents/`, use the Flow workflow for planning, implementation, sync, status, review, finish, archive, and Beads-backed task memory. + +Prefer the installed Flow skills and the repository `AGENTS.md` instructions. Do not rely on a repository `.cursor-plugin/plugin.json`; Cursor consumes rules and project instructions from its supported customization surfaces. diff --git a/.github/agents/code-reviewer.agent.md b/.github/agents/code-reviewer.agent.md new file mode 100644 index 0000000..237fe16 --- /dev/null +++ b/.github/agents/code-reviewer.agent.md @@ -0,0 +1,6 @@ +--- +name: code-reviewer +description: Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification. +--- + +Review Flow work for correctness, host integration schema mistakes, missing tests, and missing verification evidence. Lead with concrete findings. diff --git a/.github/agents/executor.agent.md b/.github/agents/executor.agent.md new file mode 100644 index 0000000..562920d --- /dev/null +++ b/.github/agents/executor.agent.md @@ -0,0 +1,6 @@ +--- +name: executor +description: Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline. +--- + +Execute Flow implementation tasks from the active spec or Beads task. Preserve context in Beads notes, follow TDD, and verify before completion claims. diff --git a/.github/agents/plan-generator.agent.md b/.github/agents/plan-generator.agent.md new file mode 100644 index 0000000..83d9094 --- /dev/null +++ b/.github/agents/plan-generator.agent.md @@ -0,0 +1,6 @@ +--- +name: plan-generator +description: Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis. +--- + +Generate Flow specs and implementation worksheets with exact file targets, TDD steps, and validation commands. diff --git a/.github/agents/prd-orchestrator.agent.md b/.github/agents/prd-orchestrator.agent.md new file mode 100644 index 0000000..22989bf --- /dev/null +++ b/.github/agents/prd-orchestrator.agent.md @@ -0,0 +1,6 @@ +--- +name: prd-orchestrator +description: Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows. +--- + +Turn broad goals into Flow PRD roadmaps. Complete research before planning child flows and validate the roadmap before presenting it. diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md index fefc640..cce1c24 100644 --- a/.opencode/INSTALL.md +++ b/.opencode/INSTALL.md @@ -36,14 +36,14 @@ Verify by asking: `What is your Flow configuration?` ## Migrating from Legacy Install -If you previously installed Flow with manual agent/command files, remove them: +If you previously installed Flow with older single-agent command files, remove them: ```bash rm -f ~/.config/opencode/agents/flow.md rm -f ~/.config/opencode/commands/flow-*.md ``` -The plugin handles everything — no separate agent or command files needed. +The plugin handles context injection. Flow's repo-local `.opencode/agents/*.md` files provide optional native subagents for hosts that read project agent files. ## Updating diff --git a/.opencode/agents/code-reviewer.md b/.opencode/agents/code-reviewer.md new file mode 100644 index 0000000..c8c92b2 --- /dev/null +++ b/.opencode/agents/code-reviewer.md @@ -0,0 +1,13 @@ +--- +name: code-reviewer +description: Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification. +mode: subagent +tools: + read: true + grep: true + glob: true + bash: true + webFetch: true +--- + +Review Flow work for behavioral bugs, invalid host schemas, stale setup commands, missing tests, and missing verification evidence. Lead with findings ordered by severity. diff --git a/.opencode/agents/executor.md b/.opencode/agents/executor.md new file mode 100644 index 0000000..1faaab5 --- /dev/null +++ b/.opencode/agents/executor.md @@ -0,0 +1,15 @@ +--- +name: executor +description: Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline. +mode: subagent +tools: + read: true + grep: true + glob: true + bash: true + edit: true + write: true + webFetch: true +--- + +Execute the current Flow task with Beads notes, Red-Green-Refactor, and fresh verification before completion claims. diff --git a/.opencode/agents/plan-generator.md b/.opencode/agents/plan-generator.md new file mode 100644 index 0000000..2aa9f83 --- /dev/null +++ b/.opencode/agents/plan-generator.md @@ -0,0 +1,15 @@ +--- +name: plan-generator +description: Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis. +mode: subagent +tools: + read: true + grep: true + glob: true + bash: true + edit: true + write: true + webFetch: true +--- + +Create implementation-ready Flow specs with exact file targets, task order, test commands, and acceptance checks. diff --git a/.opencode/agents/prd-orchestrator.md b/.opencode/agents/prd-orchestrator.md new file mode 100644 index 0000000..a8adb29 --- /dev/null +++ b/.opencode/agents/prd-orchestrator.md @@ -0,0 +1,15 @@ +--- +name: prd-orchestrator +description: Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows. +mode: subagent +tools: + read: true + grep: true + glob: true + bash: true + edit: true + write: true + webFetch: true +--- + +Analyze broad Flow goals, complete research up front, and produce PRD roadmaps split into implementation-ready flows. diff --git a/AGENTS.md b/AGENTS.md index 7dc983d..36fc58f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ Beads is a **required dependency**. Flow will offer to install it and configures - **Epics**: Define Flows and Sagas. - **Tasks**: Define implementation steps. - **Notes**: Preserve context (investigation findings, architectural decisions). -- **Markdown**: `spec.md` and `prd.md` are **Synchronized Views** of the Beads state. Run `/flow:sync` to update them. +- **Markdown**: `spec.md` and `prd.md` are **Synchronized Views** of the Beads state. Run `/flow:sync` to update them when `syncPolicy.flowSyncAfterMutation` is enabled. ## Auto-Activation @@ -48,8 +48,8 @@ To find the configured root directory: To ensure high-reasoning model routing and automated verification, all complex Flow operations MUST delegate to dedicated subagents when running in Gemini CLI: -- **Planning Phase**: Commands `/flow:prd` and `/flow:plan` delegate to `@flow:prd-orchestrator` and `@flow:plan-generator` respectively. These agents use **Gemini 3.1 Pro** and MUST invoke `superpowers:brainstorming` or `superpowers:writing-plans`. -- **Implementation Phase**: Command `/flow:implement` delegates to `@flow:executor`. This agent uses **Gemini 3.1 Pro** and MUST invoke `superpowers:test-driven-development` and `superpowers:verification-before-completion`. +- **Planning Phase**: Commands `/flow:prd` and `/flow:plan` delegate to `@prd-orchestrator` and `@plan-generator` respectively. These agents inherit host model/tool settings and MUST invoke `superpowers:brainstorming` or `superpowers:writing-plans`. +- **Implementation Phase**: Command `/flow:implement` delegates to `@executor`. This agent inherits host model/tool settings and MUST invoke `superpowers:test-driven-development` and `superpowers:verification-before-completion`. - **Validation**: All planning artifacts MUST be validated by `code-reviewer` (via `superpowers:requesting-code-review`) before being presented to the user. ## Spec & Design Documents @@ -147,14 +147,14 @@ Every host falls into one of three tiers: | Host | Tier | Entry Point | Notes | | --- | --- | --- | --- | -| **Claude Code** | first-class | `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` | Full plugin with skills, commands, and hooks. Claude subagents are optional and not currently bundled. | +| **Claude Code** | first-class | `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` + `agents/*.md` | Full plugin with skills, commands, hooks, and shared Markdown subagents. | | **Gemini CLI** | first-class | `gemini-extension.json` + `agents/*.md`, context via `GEMINI.md` | Auto-indexed gallery (topic `gemini-cli-extension`). | | **Codex CLI** | first-class | `.codex-plugin/plugin.json` + `.codex/agents/*.toml` + `.codex/config.toml` | Custom agents ship as pure TOML (tools inherited from session). | | **OpenCode** | first-class | `.opencode/plugins/flow.js` + `.opencode/agents/*.md` + native `.claude/skills/` / `.agents/skills/` reads | JS plugin wrapper + dict-schema agents. | -| **Cursor** | compatible bundle | `.cursor-plugin/plugin.json` | Hooks via `hooks/hooks-cursor.json`. | -| **VS Code / Copilot** | compatible bundle | User adds path to `chat.skillsLocations` | Raw SKILL.md tree (no wrapper extension in v0.1). | -| **Google Antigravity** | free ride | `.agent/skills/` (workspace, note **singular**) or `~/.gemini/antigravity/skills/` (global) | Symlink `.agent → .agents` in your workspace; see README install. | -| **OpenClaw** | compatible bundle | `.agents/skills/` + `AGENTS.md` | Consumes generic Agent Skills tree without extra config. | +| **Cursor** | compatible bundle | `.cursor/rules/*.mdc` + `AGENTS.md` | Rules and project instructions only; no repository Cursor plugin manifest. | +| **VS Code / Copilot** | compatible bundle | `.github/agents/*.agent.md` + `.agents/skills/` | Workspace custom agents plus Agent Skills-compatible project skills. | +| **Google Antigravity** | free ride | `.agent/skills/` (workspace, note **singular**) or `~/.gemini/antigravity/skills/` (global) | Skill-copy/symlink guidance only; see README install. | +| **OpenClaw** | compatible bundle | Runtime `sessions_spawn` + skills discovery | Consumes Flow through runtime subagents and generic Agent Skills, not a static repo manifest. | ## File Resolution @@ -162,10 +162,10 @@ Every host falls into one of three tiers: | --- | --- | | Skills | `skills//SKILL.md` | | Slash commands | `commands//.toml` | -| Subagents (Claude Code, when shipped) | `.claude-plugin/agents/.md` (`tools` as comma-separated string of Claude tool names) | | Subagents (Codex CLI) | `.codex/agents/.toml` (pure TOML; `developer_instructions` holds the prompt; no top-level `tools` — inherited from session `config.toml`) | -| Subagents (Gemini CLI) | `agents/.md` (`tools` as YAML list of Gemini tool names) | +| Subagents (Gemini CLI / Claude Code plugin) | `agents/.md` (portable Markdown, slug `name`, required `description`, host-specific tool lists omitted) | | Subagents (OpenCode) | `.opencode/agents/.md` (`tools` as dict mapping + `mode: subagent`) | +| Subagents (VS Code / Copilot) | `.github/agents/.agent.md` | | MCP servers | `mcp-servers//` | | Hooks | `hooks/*.json` + `hooks/session-start` | | Templates | `templates/skill-template/` | @@ -189,7 +189,7 @@ The following external repositories provide comprehensive, host-verified skills | `[!]` | Blocked | `blocked` | Beads -> MD | | `[-]` | Skipped | `closed` | Beads -> MD | -**IMPORTANT:** Agents MUST NOT edit these markers manually. Run `/flow:sync` to reflect Beads state in Markdown. +**IMPORTANT:** Agents MUST NOT edit these markers manually. Use `/flow:sync` to reflect Beads state in Markdown when `syncPolicy.flowSyncAfterMutation` is enabled. ## Commands @@ -244,20 +244,38 @@ Official default: ```bash repo_slug="$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//; s/-$//')" -bd init --stealth --prefix "$repo_slug" +bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents +bd config set no-git-ops true +bd config set export.auto false +bd config set export.git-add false ``` -For local-only use, prefer `.git/info/exclude` instead of editing `.gitignore`. +For local-only use, prefer `.git/info/exclude` instead of editing `.gitignore`. Flow defaults to no automatic Beads export, no auto-staging, and no git operations in Beads priming. ### Configuration (`.agents/beads.json`) ```json { "enabled": true, - "sync": "bidirectional", + "localOnly": true, + "sync": "manual", "epicPrefix": "flow", "autoCreateTasks": true, "autoSyncOnComplete": true, + "bdConfig": { + "no-git-ops": true, + "export.auto": false, + "export.git-add": false + }, + "syncPolicy": { + "flowSyncAfterMutation": true, + "autoExport": false, + "autoGitAdd": false, + "allowDoltPush": false + }, + "dolt": { + "push": "never" + }, "taskStatusMapping": { "open": "[ ]", "in_progress": "[~]", @@ -267,6 +285,12 @@ For local-only use, prefer `.git/info/exclude` instead of editing `.gitignore`. } ``` +### Sync and Export Policy + +Agents MUST read `.agents/beads.json` before running export or backend sync commands. `syncPolicy.flowSyncAfterMutation` controls whether Flow immediately runs `/flow:sync` after Beads mutations. `syncPolicy.autoExport` and `syncPolicy.autoGitAdd` map to `bd config set export.auto false` and `bd config set export.git-add false` for local-only defaults. + +Do not run `bd dolt push` unless the user explicitly requests it or `.agents/beads.json` sets `syncPolicy.allowDoltPush` to `true` and `dolt.push` to an opt-in value. + ### Key Beads Commands | Flow Action | Beads Command | @@ -279,9 +303,17 @@ For local-only use, prefer `.git/info/exclude` instead of editing `.gitignore`. | Block task | Use the active backend's blocking command | | Get ready tasks | Use the active backend's ready queue | | Add notes | Use the active backend's notes/comments command | -| Sync to git | Use the active backend's sync/export command if enabled | +| Sync/export to git | Use the active backend's sync/export command only when `syncPolicy.autoExport` or explicit user instruction allows it | +| Dolt push | Use `bd dolt push` only when `syncPolicy.allowDoltPush` is enabled or explicitly requested | | Show blocked | Use the active backend's blocked-view command | +### Memory Policy + +- Durable cross-session facts: `bd remember "..." --key :` +- Task-local findings: `bd note "..."` +- Structured tasks: prefer `bd create --context --design --acceptance --metadata --skills --spec-id` +- Session priming: run or inject `bd prime --mcp` where host hooks support MCP-aware context injection; otherwise use `bd prime` + **CRITICAL:** Keep purpose/description separate from context notes/comments: - `description`: WHY this issue exists and WHAT needs to be done @@ -395,9 +427,9 @@ State tracked in `parallel_state.json`. Uses the `invoke_subagent` tool to spawn 6. **Refactor** while green. 7. **Commit**: `(): `. 8. **Close task** in Beads with the commit SHA: `bd close --reason "[abc1234]..."`. -9. **Sync to markdown**: Run `/flow:sync` (MANDATORY — keeps spec.md readable). +9. **Sync to markdown**: Run `/flow:sync` when `syncPolicy.flowSyncAfterMutation` is enabled (default). -**CRITICAL:** After ANY Beads state change, agents MUST run `/flow:sync`. Never write markers (`[x]`, `[~]`, etc.) directly to spec.md. +**CRITICAL:** After Beads state changes, agents MUST follow `syncPolicy.flowSyncAfterMutation` in `.agents/beads.json`. Never write markers (`[x]`, `[~]`, etc.) directly to spec.md. **Important:** All commits stay local. Flow never pushes automatically. @@ -435,6 +467,7 @@ gemini extensions link . # Install official Beads brew install beads -# or -curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash +npm install -g @beads/bd +go install github.com/gastownhall/beads/cmd/bd@latest +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` diff --git a/Makefile b/Makefile index fb3e411..e626853 100644 --- a/Makefile +++ b/Makefile @@ -13,6 +13,7 @@ # limitations under the License. SHELL := /bin/bash +.SHELLFLAGS := -eu -o pipefail -c # ============================================================================= # Variables # ============================================================================= @@ -55,6 +56,12 @@ validate-skills: ## Validate skill / command / @uv run tools/validate-skills.py @echo "${OK} Skill manifests valid" +.PHONY: validate-codex-manifest +validate-codex-manifest: ## Validate Codex marketplace and plugin manifests + @echo "${INFO} Validating Codex manifests..." + @uv run tools/validate-codex-manifest.py + @echo "${OK} Codex manifests valid" + .PHONY: sync-manifests sync-manifests: ## Sync version strings across all manifests @echo "${INFO} Syncing version strings..." @@ -62,7 +69,7 @@ sync-manifests: ## Sync version strings acros @echo "${OK} Version strings in sync" .PHONY: check -check: lint validate-skills sync-manifests ## Run all quality checks (lint + validate) +check: lint validate-skills validate-codex-manifest sync-manifests ## Run all quality checks (lint + validate) @echo "${OK} All checks passed" .PHONY: build diff --git a/README.md b/README.md index 02a22fa..5b22941 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **Measure twice, code once.** -Flow is a unified toolkit for **Context-Driven Development** that works with **Claude Code**, **Gemini CLI**, **Codex CLI**, **OpenCode**, and **Google Antigravity**. It combines spec-first planning with **Beads** for persistent cross-session memory, enabling AI-assisted development with deep, persistent project awareness. +Flow is a unified toolkit for **Context-Driven Development** that works with **Claude Code**, **Gemini CLI**, **Codex CLI**, **OpenCode**, **VS Code / Copilot**, **Cursor**, **Google Antigravity**, and **OpenClaw**. It combines spec-first planning with **Beads** for persistent cross-session memory, enabling AI-assisted development with deep, persistent project awareness. ## Philosophy @@ -13,7 +13,7 @@ Control your code. By treating context as a managed artifact alongside your code ## Key Features - **Beads Integration**: Persistent task memory that survives context compaction -- **Multi-CLI Support**: Works with Claude Code, Gemini CLI, Codex CLI, OpenCode, and Google Antigravity +- **Multi-CLI Support**: Works with Claude Code, Gemini CLI, Codex CLI, OpenCode, VS Code / Copilot, Cursor, Google Antigravity, and OpenClaw - **Spec-First Development**: Create specs and plans before writing code - **TDD Workflow**: Red-Green-Refactor with >80% coverage requirements - **Knowledge Flywheel**: Capture and elevate patterns across flows (Ralph-style) @@ -194,9 +194,24 @@ OpenCode has no plugin-author hook for a plan-artifact directory. Set sensible d Cursor IDE -In Cursor, run `/add-plugin` and search for **flow** in the marketplace ([cursor.com/marketplace](https://cursor.com/marketplace)). Cursor's marketplace went live in 2.4+ and supports private team marketplaces on Team/Enterprise plans. +Cursor consumes Flow through project rules and shared repository instructions: -For local development against a checkout, drop the repo into `~/.cursor/plugins/local/flow/` and restart Cursor — Cursor auto-discovers `.cursor-plugin/plugin.json` from there. +- `.cursor/rules/flow.mdc` +- `AGENTS.md` +- project-local skills when copied or linked into `.agents/skills/` + +Do not install Flow through a repository `.cursor-plugin/plugin.json`; Flow does not ship a Cursor plugin manifest until Cursor exposes a stable documented plugin API for this use case. + + + + +
+VS Code / Copilot + + +VS Code discovers Flow custom agents from `.github/agents/*.agent.md` and shared skills from `.agents/skills/`, `.claude/skills/`, or `.github/skills/`. Flow ships workspace agent definitions for the core lifecycle agents. + +Use VS Code settings such as `chat.agentSkillsLocations` only when you need additional skill directories beyond the standard project paths.
@@ -215,6 +230,15 @@ Use a global skill install only as a fallback for environments that do not yet u + +
+OpenClaw + + +OpenClaw should consume Flow through runtime skill discovery and its native `sessions_spawn` subagent mechanism. Flow does not ship a static OpenClaw plugin manifest. + +
+
Multi-host installer (`tools/install.sh`) @@ -275,7 +299,7 @@ In Codex CLI, ask: `Use Flow to create a PRD for add user authentication` This creates `spec.md` (unified spec + plan), `learnings.md` (pattern capture log), `.agents/skills/flow-memory-keeper/SKILL.md` (project-local sync/archive/learnings/refinement skill), and a Beads epic with tasks for cross-session persistence. -> Flow uses a unified `spec.md` (no separate `plan.md`). Beads is the source of truth for task status. Use `/flow:sync` to export Beads state to `spec.md` (MANDATORY after every state change). +> Flow uses a unified `spec.md` (no separate `plan.md`). Beads is the source of truth for task status. Use `/flow:sync` to export Beads state to `spec.md` after state changes when `.agents/beads.json` has `syncPolicy.flowSyncAfterMutation` enabled. ### Implement @@ -291,7 +315,7 @@ In Codex CLI, ask: `Use Flow to implement auth` Flow follows a TDD workflow with a backend adapter: detect persistence mode, select the next task, write failing tests → implement → refactor → verify coverage → commit (conventional format) → record completion → capture learnings → `/flow-sync`. -> **CRITICAL:** Never write `[x]`, `[~]`, `[!]`, or `[-]` markers directly to `spec.md`. Beads is the source of truth. After ANY Beads state change, agents MUST run `/flow-sync` to update `spec.md`. +> **CRITICAL:** Never write `[x]`, `[~]`, `[!]`, or `[-]` markers directly to `spec.md`. Beads is the source of truth. The default `syncPolicy.flowSyncAfterMutation` setting makes agents run `/flow-sync` after Beads state changes to update `spec.md`. ## Commands @@ -383,18 +407,51 @@ Flow supports two persistence modes: ```bash repo_slug="$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//; s/-$//')" -bd init --stealth --prefix "$repo_slug" +bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents +bd config set no-git-ops true +bd config set export.auto false +bd config set export.git-add false ``` +Flow writes `.agents/beads.json` with local-only defaults: + +```json +{ + "localOnly": true, + "sync": "manual", + "bdConfig": { + "no-git-ops": true, + "export.auto": false, + "export.git-add": false + }, + "syncPolicy": { + "flowSyncAfterMutation": true, + "autoExport": false, + "autoGitAdd": false, + "allowDoltPush": false + }, + "dolt": { + "push": "never" + } +} +``` + +Do not run `bd dolt push` unless the user explicitly requests it or `.agents/beads.json` opts in with `syncPolicy.allowDoltPush: true`. + **Install paths.** ```bash # Official Beads (bd) brew install beads -# or: -curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash +npm install -g @beads/bd +go install github.com/gastownhall/beads/cmd/bd@latest +curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` +**Memory policy.** Use `bd note "..."` for task-local findings. Use `bd remember "..." --key :` for durable facts that should prime future sessions. Prefer structured task creation fields such as `--context`, `--design`, `--acceptance`, `--metadata`, `--skills`, and `--spec-id`. + +**Session priming.** Hooks should inject `bd prime --mcp` where the host supports MCP-aware context injection; otherwise run `bd prime` at session start or after compaction. + **Local-only ignore policy.** Prefer `.git/info/exclude`: ```bash @@ -473,7 +530,7 @@ Copy to your CLI's skills directory for auto-activation. ## Resources - [GitHub Issues](https://github.com/cofin/flow/issues) — Report bugs or request features -- [Beads CLI](https://github.com/steveyegge/beads) — Official `bd` task persistence layer +- [Beads CLI](https://github.com/gastownhall/beads) — Official `bd` task persistence layer ## License diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md new file mode 100644 index 0000000..84a9ca3 --- /dev/null +++ b/agents/code-reviewer.md @@ -0,0 +1,22 @@ +--- +name: code-reviewer +description: Review Flow specs, plans, and implementation changes for correctness, risk, and missing verification. +--- + +# System Prompt: Flow Code Reviewer + +You are a Flow code reviewer. Review like an owner who cares about correctness, durability, and clear evidence. + +## REVIEW PRIORITIES + +1. Behavioral bugs, regressions, and mismatches with the requested Flow outcome. +2. Missing or weak tests, especially skipped Red-Green verification. +3. Host integration mistakes: invalid manifest schemas, unsupported agent/tool fields, stale setup commands, or invented APIs. +4. Beads and Flow workflow gaps: missing notes, status drift, missing sync, or manual status marker edits. +5. Security and operational risks when setup commands, install scripts, hooks, or generated shell snippets are changed. + +## OUTPUT FORMAT + +Lead with findings. Order by severity and include concrete file references. If there are no findings, say so and list any residual test or documentation risk. + +Keep summaries secondary. Do not approve a spec, plan, or implementation unless the relevant validation evidence has been run and read. diff --git a/agents/executor.md b/agents/executor.md index bd283b6..127bfc5 100644 --- a/agents/executor.md +++ b/agents/executor.md @@ -1,18 +1,6 @@ --- -name: flow:executor -model: gemini-3.1-pro -temperature: 0.1 -tools: - - list_directory - - read_file - - write_file - - replace - - grep_search - - glob - - run_shell_command - - google_web_search - - activate_skill - - mcp_sequential-thinking_sequentialthinking +name: executor +description: Execute Flow implementation tasks with TDD, Beads notes, verification, and sync discipline. --- # System Prompt: Flow Executor diff --git a/agents/plan-generator.md b/agents/plan-generator.md index dac26c4..69b7d8e 100644 --- a/agents/plan-generator.md +++ b/agents/plan-generator.md @@ -1,20 +1,6 @@ --- -name: flow:plan-generator -model: gemini-3.1-pro -temperature: 0.2 -tools: - - list_directory - - read_file - - write_file - - replace - - grep_search - - glob - - run_shell_command - - google_web_search - - enter_plan_mode - - exit_plan_mode - - mcp_sequential-thinking_sequentialthinking - - activate_skill +name: plan-generator +description: Generate zero-ambiguity Flow specs and implementation worksheets after codebase analysis. --- # System Prompt: Flow Plan Generator diff --git a/agents/prd-orchestrator.md b/agents/prd-orchestrator.md index 8ce3b1b..9a7dfaa 100644 --- a/agents/prd-orchestrator.md +++ b/agents/prd-orchestrator.md @@ -1,20 +1,6 @@ --- -name: flow:prd-orchestrator -model: gemini-3.1-pro -temperature: 0.2 -tools: - - list_directory - - read_file - - write_file - - replace - - grep_search - - glob - - run_shell_command - - google_web_search - - enter_plan_mode - - exit_plan_mode - - mcp_sequential-thinking_sequentialthinking - - activate_skill +name: prd-orchestrator +description: Analyze broad goals and produce Flow PRD roadmaps with implementation-ready child flows. --- # System Prompt: Flow PRD Orchestrator diff --git a/commands/flow-finish.md b/commands/flow-finish.md index 0fa9f84..f9a8403 100644 --- a/commands/flow-finish.md +++ b/commands/flow-finish.md @@ -18,7 +18,7 @@ Completing flow: **$ARGUMENTS** 1. **Final Verification**: Run all tests and coverage. 2. **Beads Finalization**: Close all remaining tasks. -3. **Sync**: Run `/flow:sync` (MANDATORY) to update `spec.md` with final commit SHAs and statuses. +3. **Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to update `spec.md` with final commit SHAs and statuses. --- diff --git a/commands/flow-implement.md b/commands/flow-implement.md index 0c60db5..0344231 100644 --- a/commands/flow-implement.md +++ b/commands/flow-implement.md @@ -42,7 +42,7 @@ For each selected task: 4. **Refactor**: Clean up while remaining green. 5. **Commit**: `(): `. 6. **Close Task**: Close in Beads with the commit SHA (`bd close --reason "[abc1234]..."`). -7. **Sync**: Run `/flow:sync` to update the Markdown view. +7. **Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to update the Markdown view. --- @@ -50,7 +50,7 @@ For each selected task: 1. **Verify**: Run full test suite and check coverage. 2. **Note**: Record phase completion in Beads notes. -3. **Sync**: Run `/flow:sync` to ensure Markdown is up to date. +3. **Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to ensure Markdown is up to date. --- @@ -59,4 +59,4 @@ For each selected task: 1. **TDD MANDATORY** - Failing test first. 2. **BEADS IS SOURCE OF TRUTH** - No manual `[x]` edits in spec.md. 3. **NOTE EVERYTHING** - Record discoveries in Beads notes immediately. -4. **SYNC FREQUENTLY** - Run `/flow:sync` after every task. +4. **SYNC POLICY** - Follow `.agents/beads.json` `syncPolicy.flowSyncAfterMutation`; default setup runs `/flow:sync` after every task. diff --git a/commands/flow-plan.md b/commands/flow-plan.md index 0c9ec9c..f156771 100644 --- a/commands/flow-plan.md +++ b/commands/flow-plan.md @@ -45,7 +45,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion **PROTOCOL: Finalize artifacts and sync.** 1. **Registry**: Append to `.agents/flows.md`. -2. **Sync**: Run `/flow:sync` to generate the `spec.md` worksheet from the new Beads tasks. +2. **Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to generate the `spec.md` worksheet from the new Beads tasks. --- @@ -53,5 +53,5 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion 1. **BEADS FIRST** - Create tasks in the issue tracker before finalizing Markdown. 2. **NO CODE MODIFICATION** - Planning documents only. -3. **SYNC IS MANDATORY** - Run `/flow:sync` after planning to ensure consistency. +3. **SYNC POLICY** - Follow `syncPolicy.flowSyncAfterMutation`; default setup runs `/flow:sync` after planning to ensure consistency. 4. **HARD STOP** - End with explicit instruction to run `/flow:implement`. diff --git a/commands/flow-prd.md b/commands/flow-prd.md index 82b47a4..5b69bc9 100644 --- a/commands/flow-prd.md +++ b/commands/flow-prd.md @@ -77,7 +77,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion **PROTOCOL: Create all required files.** 1. **Registry**: Append to `.agents/flows.md`. -2. **Sync**: Run `/flow:sync` to ensure Markdown views match the new Beads state. +2. **Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` so Markdown views match the new Beads state. --- @@ -85,5 +85,5 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion 1. **BEADS FIRST** - Initialize epics and notes before finalizing Markdown. 2. **NO CODE MODIFICATION** - Planning documents only. -3. **SYNC AFTER CREATION** - Run `/flow:sync` to generate Markdown from Beads state. +3. **SYNC AFTER CREATION** - Follow `syncPolicy.flowSyncAfterMutation`; default setup runs `/flow:sync` to generate Markdown from Beads state. 4. **HARD STOP** - End with explicit instruction to run `/flow:implement`. diff --git a/commands/flow-refine.md b/commands/flow-refine.md index 559d87c..eb82bad 100644 --- a/commands/flow-refine.md +++ b/commands/flow-refine.md @@ -23,7 +23,7 @@ Refining flow: **$ARGUMENTS** - Exact file/line targets. - Implementation strategy (code snippets). - Expected failure reason for TDD. -3. **Sync Markdown**: Run `/flow:sync` to reflect these details in `spec.md`. +3. **Sync Markdown**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to reflect these details in `spec.md`. --- @@ -31,7 +31,7 @@ Refining flow: **$ARGUMENTS** **PROTOCOL: Finalize and sync.** -1. **Sync**: Run `/flow:sync` to ensure `spec.md` acts as a perfect worksheet. +1. **Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to ensure `spec.md` acts as a perfect worksheet. 2. **Hard Stop**: End with explicit instruction to run `/flow:implement`. --- @@ -40,4 +40,4 @@ Refining flow: **$ARGUMENTS** 1. **NO GUESSWORK** - Forbid vague instructions like "wire up". 2. **BEADS FIRST** - Store refined detail in Beads notes/descriptions. -3. **SYNC AFTER REFINE** - Run `/flow:sync` to generate the worksheet. +3. **SYNC AFTER REFINE** - Follow `syncPolicy.flowSyncAfterMutation`; default setup runs `/flow:sync` to generate the worksheet. diff --git a/commands/flow-revert.md b/commands/flow-revert.md index 5e5828b..41aba89 100644 --- a/commands/flow-revert.md +++ b/commands/flow-revert.md @@ -70,7 +70,7 @@ bd update {task_ids} --status open ### Markdown Sync (Manual) -**CRITICAL:** Do NOT write markers directly to spec.md. It is MANDATORY that you run `/flow-sync` to update the markdown state after any task completion or status change. +**CRITICAL:** Do NOT write markers directly to spec.md. Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` to update the markdown state after task completion or status changes. ## Critical Rules diff --git a/commands/flow-revise.md b/commands/flow-revise.md index bbeca08..5c7020a 100644 --- a/commands/flow-revise.md +++ b/commands/flow-revise.md @@ -94,7 +94,7 @@ bd update {new_task_id} --notes "Added during revision. Reason: {reason}. Create ### Markdown Sync (Manual) -**CRITICAL:** Do NOT write markers directly to spec.md. It is MANDATORY that you run `/flow-sync` to update the markdown state after any task completion or status change. +**CRITICAL:** Do NOT write markers directly to spec.md. Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` to update the markdown state after task completion or status changes. ## Phase 8: Commit Revision diff --git a/commands/flow-setup.md b/commands/flow-setup.md index d99192a..f65c809 100644 --- a/commands/flow-setup.md +++ b/commands/flow-setup.md @@ -70,7 +70,7 @@ else fi ``` -If outdated, suggest the official install: `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash` +If outdated, suggest one of the official installs: `brew install beads`, `npm install -g @beads/bd`, `go install github.com/gastownhall/beads/cmd/bd@latest`, or `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` ### 0.1.2 Legacy Specs Migration @@ -235,7 +235,7 @@ If no backend is found, ask user: > Choose a Flow task-memory backend: > -> - **A) Official Beads** (recommended) - Run `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash` +> - **A) Official Beads** (recommended) - Run `brew install beads`, `npm install -g @beads/bd`, `go install github.com/gastownhall/beads/cmd/bd@latest`, or `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` > - **B) No Beads** - Continue with markdown-only Flow state (reduced memory/resume) If a backend is installed, verify version is current and remember the selected mode for Phase 5. @@ -372,9 +372,14 @@ Based on detected languages, offer relevant styleguides: If official Beads was selected: ```bash -bd init --stealth --prefix +bd init --non-interactive --stealth --prefix --skip-agents +bd config set no-git-ops true +bd config set export.auto false +bd config set export.git-add false ``` +These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. + If no-Beads mode was selected: - Skip CLI initialization. @@ -387,7 +392,7 @@ Or prompt user: > - **Local-only** (recommended) - Add local ignores to `.git/info/exclude` > - **Shared repo policy** - Update `.gitignore` for the whole team -Create `/beads.json` with configuration. +Create `/beads.json` with local-only configuration from `templates/agent/beads.json`, including `syncPolicy.allowDoltPush: false`. --- diff --git a/commands/flow-sync.md b/commands/flow-sync.md index f079f31..6013f68 100644 --- a/commands/flow-sync.md +++ b/commands/flow-sync.md @@ -10,7 +10,7 @@ Syncing active backend state to disk for flow: **$ARGUMENTS** ## The Bridge Mandate -**CRITICAL:** `/flow:sync` is the primary bridge between the **Beads Source of Truth** and the **Markdown View**. It should be run after every task completion, note addition, or status change in Beads. +**CRITICAL:** `/flow:sync` is the primary bridge between the **Beads Source of Truth** and the **Markdown View**. Default setup runs it after task completion, note addition, or status changes when `syncPolicy.flowSyncAfterMutation` is enabled. --- @@ -22,6 +22,10 @@ Syncing active backend state to disk for flow: **$ARGUMENTS** - Use the injected **Flow Root** for all artifact paths. - Use the injected **Beads Backend** for sync and task management. 2. **Fallback (if context missing):** Use `.agents/` as the default root. +3. **Read Beads Config:** Load `/beads.json` if present. + - Respect `syncPolicy.flowSyncAfterMutation` when deciding whether a sync should run automatically. + - Respect `syncPolicy.autoExport` and `syncPolicy.autoGitAdd` before running any Beads export or staging command. + - Respect `syncPolicy.allowDoltPush` and `dolt.push` before any Dolt push operation. --- @@ -51,6 +55,8 @@ Resolve the active backend first (check hook context or beads.json): - `bd`: use the official Beads show/export command. **CRITICAL:** Pull all `notes` for the epic and its tasks. - no-Beads: skip backend export and preserve markdown-only task state. +If `syncPolicy.autoExport` is false, do not run Beads export commands as a side effect of `/flow:sync`; read from the backend and update Flow markdown views only. Do not run `bd dolt push` unless the user explicitly requests it or `.agents/beads.json` sets `syncPolicy.allowDoltPush` to `true`. + Parse the backend output. Map statuses to markdown markers: | Backend Status | Marker | @@ -124,3 +130,4 @@ Updated: .agents/specs/{flow_id}/spec.md 3. **MATCH CAREFULLY** - Match tasks by title. 4. **IDEMPOTENT** - Running sync multiple times produces the same result. 5. **NO HARDCODED BACKEND** - Support `bd` and markdown-only mode gracefully. +6. **NO IMPLICIT EXPORT OR PUSH** - Do not export, auto-stage, or run `bd dolt push` unless `.agents/beads.json` explicitly allows it or the user asks for it. diff --git a/commands/flow/cleanup.toml b/commands/flow/cleanup.toml index 575e6ff..84b58e3 100644 --- a/commands/flow/cleanup.toml +++ b/commands/flow/cleanup.toml @@ -78,7 +78,7 @@ For each Flow in `.agents/specs/`: ## 3.0 FINAL SYNC & VALIDATION 1. **Registry Sync**: Update `.agents/flows.md` and ensure all links are valid. -2. **Global Sync**: Run `/flow:sync` for all active flows to finalize Beads-to-Markdown state. +2. **Global Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` for all active flows to finalize Beads-to-Markdown state. 3. **Integrity Check**: Confirm no information was lost during reorganization. --- diff --git a/commands/flow/finish.toml b/commands/flow/finish.toml index c3a9cf5..45c4cae 100644 --- a/commands/flow/finish.toml +++ b/commands/flow/finish.toml @@ -12,7 +12,7 @@ CRITICAL: You must have FRESH VERIFICATION EVIDENCE before claiming anything pas 1. **Final Verification:** Run all tests and check coverage. 2. **Beads Finalization:** Close all remaining tasks in the active backend. -3. **Sync:** Run `/flow:sync` (MANDATORY) to update the Markdown view with final statuses and notes. +3. **Sync:** Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to update the Markdown view with final statuses and notes. --- diff --git a/commands/flow/implement.toml b/commands/flow/implement.toml index 0f8d0f8..432fac3 100644 --- a/commands/flow/implement.toml +++ b/commands/flow/implement.toml @@ -4,7 +4,7 @@ prompt = """ You are a delegator for the Flow framework. Your task is to transition the current request to the high-reasoning "Executor" subagent to ensure proper model routing and TDD discipline. ## 1.1 DELEGATION -1. **Delegate**: Invoke the `@flow:executor` subagent with the user's request: `{{args}}`. +1. **Delegate**: Invoke the `@executor` subagent with the user's request: `{{args}}`. ## 1.2 CONTEXT PASS-THROUGH Ensure the subagent receives: diff --git a/commands/flow/plan.toml b/commands/flow/plan.toml index 1d189c7..e5b27f3 100644 --- a/commands/flow/plan.toml +++ b/commands/flow/plan.toml @@ -5,7 +5,7 @@ You are a delegator for the Flow framework. Your task is to transition the curre ## 1.1 INITIALIZATION 1. **Enter Plan Mode**: You MUST call `enter_plan_mode` immediately with the reason `"Delegating to Plan Generator for Flow worksheet planning"`. -2. **Delegate**: Invoke the `@flow:plan-generator` subagent with the user's original goal: `{{args}}`. +2. **Delegate**: Invoke the `@plan-generator` subagent with the user's original goal: `{{args}}`. ## 1.2 CONTEXT PASS-THROUGH Ensure the subagent receives: diff --git a/commands/flow/prd.toml b/commands/flow/prd.toml index 4d88546..ca56db0 100644 --- a/commands/flow/prd.toml +++ b/commands/flow/prd.toml @@ -5,7 +5,7 @@ You are a delegator for the Flow framework. Your task is to transition the curre ## 1.1 INITIALIZATION 1. **Enter Plan Mode**: You MUST call `enter_plan_mode` immediately with the reason `"Delegating to PRD Orchestrator for saga planning"`. -2. **Delegate**: Invoke the `@flow:prd-orchestrator` subagent with the user's original goal: `{{args}}`. +2. **Delegate**: Invoke the `@prd-orchestrator` subagent with the user's original goal: `{{args}}`. ## 1.2 CONTEXT PASS-THROUGH Ensure the subagent receives: diff --git a/commands/flow/refine.toml b/commands/flow/refine.toml index 7fec341..2797d33 100644 --- a/commands/flow/refine.toml +++ b/commands/flow/refine.toml @@ -16,7 +16,7 @@ CRITICAL: You must validate the success of every tool call. - Exact file/line targets. - Implementation strategy (code snippets). - Expected failure reason for TDD. -4. **Sync Markdown:** Run `/flow:sync` to reflect these details in `spec.md`. +4. **Sync Markdown:** Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to reflect these details in `spec.md`. Repeat until the task no longer depends on avoidable guesswork. @@ -25,6 +25,6 @@ Repeat until the task no longer depends on avoidable guesswork. ## 5.0 COMPLETION (HARD STOP) Announce: > "**REFINEMENT COMPLETE - IMPLEMENTATION READY** -> Flow '' refined in Beads. Run `/flow:sync` to see the worksheet. +> Flow '' refined in Beads. Run `/flow:sync` to see the worksheet when `syncPolicy.flowSyncAfterMutation` is enabled. > To begin implementation, run: `/flow:implement `" """ diff --git a/commands/flow/refresh.toml b/commands/flow/refresh.toml index 085682d..fe7a2b4 100644 --- a/commands/flow/refresh.toml +++ b/commands/flow/refresh.toml @@ -85,7 +85,7 @@ Since last sync (, ago): ## Critical Rules 1. **NEVER OVERWRITE MANUAL EDITS** - Merge changes into spec.md, don't replace 2. **ASK ON CONFLICT** - If conflicts detected, present both versions and ask user to resolve -3. **SYNC AT END** - Always run `/flow:sync` equivalent at the end to ensure spec.md reflects final state +3. **SYNC AT END** - Follow `syncPolicy.flowSyncAfterMutation`; default setup runs `/flow:sync` equivalent at the end to ensure spec.md reflects final state 4. **LOG IN BACKEND** - Record the refresh through the active backend's note/comment mechanism when a backend is enabled 5. **READ-ONLY ON CODE** - Never modify source files, only `.agents/` context 6. **WORKFLOW DRIFT COUNTS** - Treat stale canonical commands, backend assumptions, and ignore policy as refresh work, not optional cleanup diff --git a/commands/flow/revert.toml b/commands/flow/revert.toml index 32700cc..0ff6d87 100644 --- a/commands/flow/revert.toml +++ b/commands/flow/revert.toml @@ -166,7 +166,7 @@ Handles non-linear Git histories (rebase, squash, merge commits). ``` 5. **Markdown Sync (Manual):** - - It is MANDATORY that you run `/flow:sync` to export Beads state to spec.md on commit. + - Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to export Beads state to spec.md on commit. - **Do NOT manually edit spec.md markers** - use the command instead. 6. **Sync and Prime:** @@ -197,4 +197,4 @@ Handles non-linear Git histories (rebase, squash, merge commits). 2. **FIND ALL COMMITS** - Include plan-update commits, not just code commits 3. **BEADS FIRST** - Update task status in Beads after revert 5. **PRESERVE LEARNINGS** - Learnings.md is NOT reverted (institutional knowledge) -""" \ No newline at end of file +""" diff --git a/commands/flow/revise.toml b/commands/flow/revise.toml index 1da3376..719593c 100644 --- a/commands/flow/revise.toml +++ b/commands/flow/revise.toml @@ -117,7 +117,7 @@ bd close {task_id} --reason "Removed in revision" ### Markdown Sync (Manual) -**CRITICAL:** Do NOT write markers directly to spec.md. It is MANDATORY that you run `/flow:sync` to update the markdown state after any task completion or status change. +**CRITICAL:** Do NOT write markers directly to spec.md. Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to update the markdown state after task completion or status changes. ## Phase 8: Commit Revision @@ -154,4 +154,4 @@ Logged in: revisions.md 2. **BEADS FIRST** - Update Beads before syncing markdown 4. **PRESERVE HISTORY** - Never delete, only append to revisions.md 5. **VALIDATE** - Ensure acceptance criteria remain testable -""" \ No newline at end of file +""" diff --git a/commands/flow/setup.toml b/commands/flow/setup.toml index a50440e..295f74e 100644 --- a/commands/flow/setup.toml +++ b/commands/flow/setup.toml @@ -41,18 +41,20 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa > "Flow supports two persistence modes: > A) Install official Beads (`bd`) (recommended) > - brew install beads - > - or curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash + > - npm install -g @beads/bd + > - go install github.com/gastownhall/beads/cmd/bd@latest + > - or curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash > B) Continue without Beads (docs/plans/lightweight mode)" If A selected: ```bash - curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash + curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` If B selected, continue in no-Beads mode. Do NOT halt. 3. **Default initialization rules:** - - Official Beads MUST use `bd init --stealth --prefix "$repo_slug"`. + - Official Beads MUST use `bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents`, then set `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`. - Prefer `.git/info/exclude` for local-only ignores instead of editing repo `.gitignore`. 4. **Continue:** Once the backend choice is clear, proceed to 1.1. @@ -103,7 +105,11 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa ``` - If `bd` is available, verify with `bd --version`. - If unavailable, continue alignment in no-Beads mode instead of blocking the rest of setup. - - If official Beads should be installed or refreshed, suggest: `curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash` + - If official Beads should be installed or refreshed, suggest one of: + - `brew install beads` + - `npm install -g @beads/bd` + - `go install github.com/gastownhall/beads/cmd/bd@latest` + - `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` 2. **Legacy Specs Migration:** Scan for legacy spec locations: @@ -628,7 +634,10 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa If A selected: ```bash - bd init --stealth --prefix "$repo_slug" + bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents + bd config set no-git-ops true + bd config set export.auto false + bd config set export.git-add false ``` If B selected, skip backend initialization and continue in no-Beads mode. @@ -638,11 +647,26 @@ Use `${FLOW_INSTALL_ROOT}` in every command below that references shipped templa ```json { "enabled": true, - "sync": "bidirectional", + "localOnly": true, + "sync": "manual", "epicPrefix": "flow", "autoCreateTasks": true, "autoSyncOnComplete": true, "compactOnArchive": false, + "bdConfig": { + "no-git-ops": true, + "export.auto": false, + "export.git-add": false + }, + "syncPolicy": { + "flowSyncAfterMutation": true, + "autoExport": false, + "autoGitAdd": false, + "allowDoltPush": false + }, + "dolt": { + "push": "never" + }, "taskStatusMapping": { "pending": "[ ]", "in_progress": "[~]", diff --git a/commands/flow/sync.toml b/commands/flow/sync.toml index d64fd7f..71d2df7 100644 --- a/commands/flow/sync.toml +++ b/commands/flow/sync.toml @@ -13,6 +13,11 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai 1. **Check Arguments:** * If `{{args}}` contains `--export`, set a flag to generate an export summary at the end. * Otherwise, standard sync and refresh. +2. **Read Sync Policy:** + * Load `.agents/beads.json` if present. + * Respect `syncPolicy.flowSyncAfterMutation` when deciding whether this command should run automatically. + * Respect `syncPolicy.autoExport` and `syncPolicy.autoGitAdd` before any backend export or staging command. + * Respect `syncPolicy.allowDoltPush` and `dolt.push` before any Dolt push operation. --- @@ -24,6 +29,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai 3. **Resolve Active Backend:** `bd` or `none`. 4. **Fetch States:** * **Backend State:** Pull all tasks AND notes/comments. + * If `syncPolicy.autoExport` is false, read backend state without running Beads export as a side effect. 5. **Regenerate Spec Task Section:** * Map backend statuses to markdown markers. * Match tasks by title. @@ -85,6 +91,7 @@ CRITICAL: You must validate the success of every tool call. If any tool call fai * Gather Git Stats (commits) and Test Coverage. * Output Markdown/JSON report to `.agents/export.[md|json]`. * Announce completion of export. +2. Do not run `bd dolt push` unless the user explicitly requested it or `.agents/beads.json` sets `syncPolicy.allowDoltPush` to `true`. --- @@ -108,4 +115,5 @@ Report: 3. **DETECT DON'T ASSUME** - Verify before updating tech-stack.md or patterns.md 4. **ASK FIRST** - Confirm documentation changes with user 5. **NO HARDCODED BACKEND** - Support `bd` and markdown-only mode gracefully +6. **NO IMPLICIT EXPORT OR PUSH** - Do not export, auto-stage, or run `bd dolt push` unless `.agents/beads.json` explicitly allows it or the user asks for it """ diff --git a/docs/multi-host-plugin-patterns.md b/docs/multi-host-plugin-patterns.md index 28e7d96..3c75584 100644 --- a/docs/multi-host-plugin-patterns.md +++ b/docs/multi-host-plugin-patterns.md @@ -10,12 +10,15 @@ Reference for any repo that ships skills, commands, hooks, or agents across **Cl | `.claude-plugin/plugin.json` | Claude Code | Plugin manifest — declares skills, commands, hooks, **`userConfig`** | | `.agents/plugins/marketplace.json` | Codex CLI | Marketplace catalog (`codex plugin marketplace add owner/repo`) | | `.codex-plugin/plugin.json` | Codex CLI | Plugin manifest with `interface` block | +| `.codex/agents/*.toml` | Codex CLI | Repo-local TOML subagents that inherit session tools | | `gemini-extension.json` | Gemini CLI | Extension manifest — `plan.directory`, **`excludeTools`**, `contextFileName` | +| `agents/*.md` | Gemini CLI / Claude Code | Shared Markdown subagents with slug names and descriptions | | `hooks/hooks.json` | Gemini CLI | Auto-discovered hook manifest | | `hooks/hooks-claude.json` | Claude Code | Per-host hook manifest (referenced from `.claude-plugin/plugin.json`) | -| `hooks/hooks-cursor.json` | Cursor | Per-host hook manifest | -| `.cursor-plugin/plugin.json` | Cursor | Marketplace listing manifest | +| `.cursor/rules/*.mdc` | Cursor | Workspace rules consumed by Cursor's supported customization surface | +| `.github/agents/*.agent.md` | VS Code / Copilot | Workspace custom agents | | `.opencode/plugins/.js` | OpenCode | Local plugin entrypoint with managed-config awareness | +| `.opencode/agents/*.md` | OpenCode | Native subagents with `mode: subagent` | | `.gitignore` | All | Must `!`-include `.agents/plugins/marketplace.json` if `.agents/` is otherwise ignored | If `.agents/` is gitignored, use `.agents/*` (NOT `.agents/`) so git descends into the directory and honors re-includes. Then `!.agents/plugins/marketplace.json` works. @@ -45,6 +48,7 @@ If `.agents/` is gitignored, use `.agents/*` (NOT `.agents/`) so git descends in "version": "", "skills": ["./skills/"], "commands": ["./commands/"], + "agents": ["./agents/"], "hooks": "./hooks/hooks-claude.json", "userConfig": { "": { @@ -108,6 +112,8 @@ If `.agents/` is gitignored, use `.agents/*` (NOT `.agents/`) so git descends in } ``` +**Repo-local subagents** (`.codex/agents/.toml`) are pure TOML. Include `name`, `description`, and `developer_instructions`; do not include `tools`, because Codex inherits tools from the active session configuration. + **Install command** (Codex CLI 0.117+): ```bash @@ -170,31 +176,30 @@ Use `${extensionPath}` (Gemini's install-root variable) and `${/}` (cross-platfo **`plan.directory`** is the only first-class plugin-author hook for redirecting plan-mode artifacts. None of Claude/Codex/OpenCode have an equivalent — they're all user-side config. -### Cursor (2.4+) +### Cursor -**Plugin manifest** (`.cursor-plugin/plugin.json` at repo root): +Use Cursor rules and shared project instructions: -```json -{ - "name": "", - "displayName": "", - "version": "", - "author": { "name": "" }, - "description": "<...>", - "keywords": ["..."], - "license": "MIT", - "homepage": "https://github.com//", - "repository": "https://github.com//", - "hooks": "./hooks/hooks-cursor.json" -} -``` +- `.cursor/rules/.mdc` +- `AGENTS.md` +- copied or linked Agent Skills under `.agents/skills/` when needed -**Marketplace** ([cursor.com/marketplace](https://cursor.com/marketplace)): +Do not present `.cursor-plugin/plugin.json` as a supported Flow surface until Cursor documents a stable plugin API for repository-distributed agent plugins. + +### VS Code / Copilot + +**Workspace custom agents** live in `.github/agents/*.agent.md`: + +```markdown +--- +name: planner +description: Generate an implementation plan +--- + +Write a concrete plan with tests and validation commands. +``` -- Install in editor: `/add-plugin` → search. -- Submit: PR to [github.com/cursor/plugins](https://github.com/cursor/plugins) (open-source only) OR web form at cursor.com/marketplace/publish. -- Local dev: drop into `~/.cursor/plugins/local//` and restart. -- Team/Enterprise plans support **private team marketplaces** with central governance. +VS Code also discovers project skills from `.github/skills/`, `.claude/skills/`, and `.agents/skills/`. Use `chat.agentSkillsLocations` only for additional custom locations. ### OpenCode @@ -301,7 +306,7 @@ git clone https://github.com//.git ~/.config/opencode/ ln -sf ~/.config/opencode//.opencode/plugins/.js ~/.config/opencode/plugins/.js # Cursor -# In editor: /add-plugin → search → install +# Add `.cursor/rules/*.mdc` and shared `AGENTS.md` instructions. ``` ## What NOT to ship @@ -319,7 +324,7 @@ ln -sf ~/.config/opencode//.opencode/plugins/.js ~/.config/opencode/ python3 -c "import json; [json.load(open(p)) for p in [ '.claude-plugin/marketplace.json', '.claude-plugin/plugin.json', '.agents/plugins/marketplace.json', '.codex-plugin/plugin.json', - '.cursor-plugin/plugin.json', 'gemini-extension.json', + 'gemini-extension.json', 'hooks/hooks.json', 'hooks/hooks-claude.json', 'hooks/hooks-cursor.json' ]]" diff --git a/gemini-extension.json b/gemini-extension.json index 5615fc6..bef457b 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,7 +1,7 @@ { "name": "flow", "description": "Unified toolkit for Context-Driven Development with spec-first planning, TDD workflow, and Beads integration", - "version": "0.20.0", + "version": "0.20.1", "contextFileName": "GEMINI.md", "plan": { "directory": ".agents" diff --git a/hooks/detect-env.ps1 b/hooks/detect-env.ps1 index 7957685..c44ac06 100644 --- a/hooks/detect-env.ps1 +++ b/hooks/detect-env.ps1 @@ -24,7 +24,7 @@ function Get-BeadsBackend { Write-Host "- **Beads Backend**: Missing (None)" $beads_br = Get-Command br -ErrorAction SilentlyContinue if ($beads_br) { - Write-Host "- **Migration Notice**: Detected legacy 'br' (beads_rust). Flow no longer supports br. Install official Beads: brew install beads (or https://github.com/steveyegge/beads)." + Write-Host "- **Migration Notice**: Detected legacy 'br' (beads_rust). Flow no longer supports br. Install official Beads: brew install beads (or https://github.com/gastownhall/beads)." } return $null } @@ -231,7 +231,7 @@ function Get-FlowMandate($rootDir) { Write-Host "- **Deep Research First**: Do NOT defer research to implementation. ALL analysis and architectural decisions MUST be completed upfront." Write-Host "- **Stateless Executor Test**: A plan is only 'Ready' if an agent with ZERO context can implement it 100% correctly based ONLY on the worksheet." Write-Host "- **TDD Discipline**: Follow the Red-Green-Refactor cycle and verify coverage as outlined in the `flow` skill." - Write-Host "- **Sync Requirement**: Run \"/flow:sync\" after any change to Beads state or project structure." + Write-Host "- **Sync Requirement**: Follow $rootDir/beads.json syncPolicy.flowSyncAfterMutation; default setup runs /flow:sync after Beads changes but does not auto-export, auto-stage, or run bd dolt push." } function Main { @@ -248,4 +248,3 @@ function Main { } Main - diff --git a/hooks/detect-env.sh b/hooks/detect-env.sh index 49b1333..35bd8a8 100755 --- a/hooks/detect-env.sh +++ b/hooks/detect-env.sh @@ -51,7 +51,7 @@ detect_beads() { else echo "- **Beads Backend**: Missing (None)" if command -v br >/dev/null 2>&1; then - echo "- **Migration Notice**: Detected legacy \`br\` (beads_rust). Flow no longer supports br. Install official Beads: brew install beads (or https://github.com/steveyegge/beads)." + echo "- **Migration Notice**: Detected legacy \`br\` (beads_rust). Flow no longer supports br. Install official Beads: brew install beads (or https://github.com/gastownhall/beads)." fi fi } @@ -250,7 +250,7 @@ flow_mandate() { - **Deep Research First**: Do NOT defer research to implementation. ALL analysis and architectural decisions MUST be completed upfront. - **Stateless Executor Test**: A plan is only 'Ready' if an agent with ZERO context can implement it 100% correctly based ONLY on the worksheet. - **TDD Discipline**: Follow the Red-Green-Refactor cycle and verify coverage as outlined in the \`flow\` skill. -- **Sync Requirement**: Run \`/flow:sync\` after any change to Beads state or project structure. +- **Sync Requirement**: Follow \`${root_dir}/beads.json\` \`syncPolicy.flowSyncAfterMutation\`; default setup runs \`/flow:sync\` after Beads changes but does not auto-export, auto-stage, or run \`bd dolt push\`. EOF } @@ -279,4 +279,3 @@ main() { } main "$@" - diff --git a/package.json b/package.json index 851fb5b..39c5dc7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "flow", - "version": "0.20.0", + "version": "0.20.1", "description": "Unified toolkit for Context-Driven Development", "type": "module", "main": ".opencode/plugins/flow.js", diff --git a/pyproject.toml b/pyproject.toml index c242e89..13508ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "flow" -version = "0.20.0" +version = "0.20.1" description = "Unified toolkit for Context-Driven Development" authors = [ { name = "cofin" }, @@ -26,7 +26,7 @@ dev = [ allow_dirty = true commit = false commit_args = "--no-verify" -current_version = "0.20.0" +current_version = "0.20.1" ignore_missing_files = false ignore_missing_version = false message = "chore(release): bump to v{new_version}" @@ -76,11 +76,6 @@ filename = ".claude-plugin/marketplace.json" replace = '"version": "{new_version}"' search = '"version": "{current_version}"' -[[tool.bumpversion.files]] -filename = ".cursor-plugin/plugin.json" -replace = '"version": "{new_version}"' -search = '"version": "{current_version}"' - [[tool.bumpversion.files]] filename = ".codex-plugin/plugin.json" replace = '"version": "{new_version}"' diff --git a/skills/flow/SKILL.md b/skills/flow/SKILL.md index ec5828e..8b83eee 100644 --- a/skills/flow/SKILL.md +++ b/skills/flow/SKILL.md @@ -52,6 +52,20 @@ Flow supports two persistence modes: - **Official Beads (`bd`)** - default - **No Beads** - degraded mode for planning, docs, and lightweight local work +### Beads Sync Policy + +Read `.agents/beads.json` before running backend export, git-add, or Dolt operations. Default Flow setup writes: + +- `bdConfig.no-git-ops: true` +- `bdConfig.export.auto: false` +- `bdConfig.export.git-add: false` +- `syncPolicy.flowSyncAfterMutation: true` +- `syncPolicy.autoExport: false` +- `syncPolicy.autoGitAdd: false` +- `syncPolicy.allowDoltPush: false` + +Do not run `bd dolt push` unless the user explicitly requests it or `.agents/beads.json` sets `syncPolicy.allowDoltPush` to `true` and opts in via `dolt.push`. + ## Universal File Resolution Protocol **To locate files within Flow context:** @@ -103,7 +117,7 @@ Flow supports two persistence modes: -**CRITICAL:** Never write `[x]`, `[~]`, `[!]`, or `[-]` markers to spec.md manually. Beads is the source of truth — after ANY Beads state change, you MUST run `/flow:sync` to keep spec.md in sync. +**CRITICAL:** Never write `[x]`, `[~]`, `[!]`, or `[-]` markers to spec.md manually. Beads is the source of truth. Run `/flow:sync` after Beads state changes when `syncPolicy.flowSyncAfterMutation` is enabled, and never run export, auto-stage, or Dolt push operations unless `.agents/beads.json` allows them. **CRITICAL:** Read `.agents/workflow.md` before planning or implementation and prefer the repo's canonical commands there. If the repo clearly has better aggregate commands than the workflow currently documents, refresh the workflow or capture the correction in learnings/knowledge. @@ -225,7 +239,8 @@ When Flow skill is active: - If `.agents/skills/flow-memory-keeper/SKILL.md` exists, invoke it for sync, archive, finish, and failure/refinement work. - If the user repeats a correction or sounds frustrated about something being forgotten, treat that as mandatory knowledge capture rather than optional polish. - Warn if tech-stack changes without documentation. -- Enforce mandatory `/flow:sync` after any Beads state change. +- Enforce `/flow:sync` after Beads state changes when `syncPolicy.flowSyncAfterMutation` is enabled. +- Do not run `bd dolt push` unless the user explicitly asks or `.agents/beads.json` opts in with `syncPolicy.allowDoltPush`. - Prefer canonical repo commands (setup, lint, test, typecheck, verify) as defined in the **Core Project Truths** section of the hook context or in `.agents/workflow.md`. - Treat repeated reminders like "use make lint" or "don't forget to test" as workflow failures that must be captured and elevated. - **Mandatory Superpowers Integration:** If Superpowers is detected, all workflows (PRD, Plan, Implement) MUST follow the **Superpowers Protocol** above. @@ -301,8 +316,8 @@ These can be dispatched as specialized subagents during code review or design ev - - -- -- +- +- - ## Shared Styleguide Baseline diff --git a/skills/flow/references/cleanup.md b/skills/flow/references/cleanup.md index 2841bcf..4b636f5 100644 --- a/skills/flow/references/cleanup.md +++ b/skills/flow/references/cleanup.md @@ -83,7 +83,7 @@ For each Flow in `.agents/specs/`: ## 3.0 FINAL SYNC & VALIDATION 1. **Registry Sync**: Update `.agents/flows.md` and ensure all links are valid. -2. **Global Sync**: Run `/flow:sync` for all active flows to finalize Beads-to-Markdown state. +2. **Global Sync**: Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` for all active flows to finalize Beads-to-Markdown state. 3. **Integrity Check**: Confirm no information was lost during reorganization. --- diff --git a/skills/flow/references/finish.md b/skills/flow/references/finish.md index 93104f7..c60607b 100644 --- a/skills/flow/references/finish.md +++ b/skills/flow/references/finish.md @@ -41,7 +41,7 @@ IRON LAW: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE # Ensure spec.md reflects current state ``` - Run `/flow:sync` to update spec.md from Beads. + Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` to update spec.md from Beads. **If any check fails:** Report actual results. Do NOT proceed until issues resolved. diff --git a/skills/flow/references/implement.md b/skills/flow/references/implement.md index 1d3d485..e0778e4 100644 --- a/skills/flow/references/implement.md +++ b/skills/flow/references/implement.md @@ -201,7 +201,7 @@ At end of each phase: 4. **Create checkpoint commit**: `git commit -m "chore(checkpoint): complete phase {N}"` 5. **Prompt for pattern elevation**: "Are there learnings from this phase to elevate to `patterns.md`?" 6. **Record checkpoint in Beads**: use the active backend's note/comment command -7. **Sync to markdown**: run `/flow:sync` (MANDATORY) +7. **Sync to markdown**: follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow:sync` 8. **Ask user to verify** **Verification red flags — STOP before claiming completion:** diff --git a/skills/flow/references/refresh.md b/skills/flow/references/refresh.md index a24df70..0b5a2c9 100644 --- a/skills/flow/references/refresh.md +++ b/skills/flow/references/refresh.md @@ -67,6 +67,6 @@ No conflicts detected. - Never overwrite manual edits to spec.md — merge changes, don't replace - If conflicts are detected, present both versions and ask the user to resolve -- Always run `/flow:sync` at the end to ensure spec.md reflects final state +- Follow `syncPolicy.flowSyncAfterMutation`; default setup runs `/flow:sync` at the end to ensure spec.md reflects final state - Log the refresh action through the active backend's note/comment mechanism - Treat workflow drift as real refresh work, not optional cleanup diff --git a/skills/flow/references/setup.md b/skills/flow/references/setup.md index 3898ad0..cdb2c0b 100644 --- a/skills/flow/references/setup.md +++ b/skills/flow/references/setup.md @@ -252,9 +252,15 @@ repo_slug="$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr Official default: ```bash -bd init --stealth --prefix "$repo_slug" +bd init --non-interactive --stealth --prefix "$repo_slug" --skip-agents +bd config set no-git-ops true +bd config set export.auto false +bd config set export.git-add false ``` +Flow owns the host instruction files, so Beads setup must skip its generated agent files. +The config commands keep Beads local-only by default: no automatic export, no auto-staging, and no git operations in `bd prime` output. + Or prompt user: > **Beads mode:** @@ -262,7 +268,7 @@ Or prompt user: > - **Local-only** (recommended) - Add ignores to `.git/info/exclude` > - **Team** - Commit to repo for team sharing -Create `/beads.json` with configuration. +Create `/beads.json` with local-only configuration from `templates/agent/beads.json`, including `syncPolicy.allowDoltPush: false`. --- diff --git a/templates/agent/beads.json b/templates/agent/beads.json index 4f269eb..200c252 100644 --- a/templates/agent/beads.json +++ b/templates/agent/beads.json @@ -1,10 +1,25 @@ { "enabled": true, - "sync": "bidirectional", + "localOnly": true, + "sync": "manual", "epicPrefix": "flow", "autoCreateTasks": true, "autoSyncOnComplete": true, "compactOnArchive": false, + "bdConfig": { + "no-git-ops": true, + "export.auto": false, + "export.git-add": false + }, + "syncPolicy": { + "flowSyncAfterMutation": true, + "autoExport": false, + "autoGitAdd": false, + "allowDoltPush": false + }, + "dolt": { + "push": "never" + }, "taskStatusMapping": { "pending": "[ ]", "in_progress": "[~]", diff --git a/templates/agent/workflow.md b/templates/agent/workflow.md index f33edcd..dc31da7 100644 --- a/templates/agent/workflow.md +++ b/templates/agent/workflow.md @@ -18,7 +18,7 @@ ## Guiding Principles -1. **Beads backend is the Source of Truth:** Use official Beads (`bd`) and run `/flow:sync` to export task state to spec.md when needed. +1. **Beads backend is the Source of Truth:** Use official Beads (`bd`) and run `/flow:sync` to export task state to spec.md when `syncPolicy.flowSyncAfterMutation` is enabled. 2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation 3. **Test-Driven Development:** Write unit tests before implementing functionality 4. **High Code Coverage:** Aim for >80% code coverage for all modules @@ -39,15 +39,18 @@ Flow supports two modes: Configured for local-only use during setup unless the user explicitly asks for shared repo state. +Default setup writes `.agents/beads.json` with `syncPolicy.autoExport: false`, `syncPolicy.autoGitAdd: false`, and `syncPolicy.allowDoltPush: false`. It also applies `bd config set no-git-ops true`, `bd config set export.auto false`, and `bd config set export.git-add false`. + ### Session Protocol **Session Start:** -Use the active backend's session-start commands. +Use the active backend's session-start commands. Prefer `bd prime --mcp` when host hooks inject MCP-aware context; otherwise use `bd prime`. **Session End:** For local-only ignores, prefer `.git/info/exclude` before `.gitignore`. +Do not run `bd dolt push` unless the user explicitly asks or `.agents/beads.json` opts in with `syncPolicy.allowDoltPush`. > If no supported Beads backend is available, workflow degrades gracefully to git-only tracking. @@ -78,6 +81,8 @@ bd note "" - `--description`: Purpose and goal - notes/comments: Context for future agents +- durable cross-session facts: `bd remember "..." --key :` +- structured issue context: prefer `--context`, `--design`, `--acceptance`, `--metadata`, `--skills`, and `--spec-id` when available - Priority levels: P0=critical, P1=high, P2=medium, P3=low, P4=backlog ## Task Workflow @@ -86,7 +91,7 @@ All tasks follow a strict lifecycle: ### Task Workflow (TDD) - Beads-First -**CRITICAL:** Beads is the source of truth. Never write `[x]`, `[~]`, `[!]`, or `[-]` markers to spec.md manually. After ANY Beads state change, agents MUST run `/flow:sync` to update spec.md. +**CRITICAL:** Beads is the source of truth. Never write `[x]`, `[~]`, `[!]`, or `[-]` markers to spec.md manually. After Beads state changes, agents MUST follow `syncPolicy.flowSyncAfterMutation` and run `/flow:sync` when it is enabled. **Companion Skills Usage:** @@ -144,7 +149,7 @@ All tasks follow a strict lifecycle: 9. **Record Task Completion (Beads-First):** - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%h"`). - **Step 9.2: Close in Beads:** use the active backend to record completion - - **Step 9.3 (Manual Sync):** You MUST run `/flow-sync` to update the markdown state in `spec.md` so it aligns with Beads. + - **Step 9.3 (Manual Sync):** Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` so `spec.md` aligns with Beads. - **Do NOT manually edit spec.md markers** - they are managed by running `/flow-sync`. 10. **Log Learnings:** @@ -247,7 +252,7 @@ Validated repo-native commands are also high-signal learnings. If the project al - Update the epic with verification summary using the active backend's note/comment command 8. **Sync to spec.md (Manual):** - - You MUST run `/flow-sync` to update the markdown state in `spec.md` so it aligns with Beads for human-readable status. + - Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` so `spec.md` aligns with Beads for human-readable status. - **Do NOT manually edit spec.md** - Beads is source of truth, and you must sync it using the command. 9. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been recorded in Beads. diff --git a/templates/opencode/agents/flow.md b/templates/opencode/agents/flow.md index 7cec378..ae94698 100644 --- a/templates/opencode/agents/flow.md +++ b/templates/opencode/agents/flow.md @@ -32,11 +32,16 @@ A flow is a logical unit of work (feature, bug fix, refactor). Each flow has: ### Beads Integration (Source of Truth) Beads provides persistent cross-session memory: ```bash -bd init --stealth --prefix # Initialize official Beads +bd init --non-interactive --stealth --prefix --skip-agents # Initialize official Beads without generated host instruction files +bd config set no-git-ops true +bd config set export.auto false +bd config set export.git-add false bd status # Workspace overview bd ready # Ready queue ``` +Read `.agents/beads.json` before export or backend sync. Default `syncPolicy` keeps Flow's markdown sync enabled, disables Beads auto-export/auto-stage, and sets `allowDoltPush` false. Do not run `bd dolt push` unless the user explicitly asks or the config opts in. + ### Task Workflow (TDD) - Beads-First 1. **Select task** from the active backend's ready queue (Beads is source of truth) 2. **Mark in progress** via the active backend @@ -46,9 +51,9 @@ bd ready # Ready queue 5. **Refactor** while green 6. Commit with conventional format 7. **Sync to Beads** via the active backend's completion flow -8. **Sync to markdown:** run `/flow:sync` (MANDATORY — keeps spec.md readable) +8. **Sync to markdown:** run `/flow:sync` when `syncPolicy.flowSyncAfterMutation` is true (default) -**CRITICAL:** It is MANDATORY that after ANY Beads state change (close, block, skip, revert, revise), agents run `/flow:sync` to update spec.md. Never write markers (`[x]`, `[~]`, `[!]`, `[-]`) directly to spec.md. +**CRITICAL:** Never write markers (`[x]`, `[~]`, `[!]`, `[-]`) directly to spec.md. Use `/flow:sync` for markdown status updates, and respect `.agents/beads.json` before running export, auto-stage, or Dolt push operations. 9. Log learnings in learnings.md ### Directory Structure diff --git a/templates/opencode/commands/flow-finish.md b/templates/opencode/commands/flow-finish.md index c6d0555..9d09ed4 100644 --- a/templates/opencode/commands/flow-finish.md +++ b/templates/opencode/commands/flow-finish.md @@ -21,7 +21,7 @@ Complete a Flow's development work: verify tests, dispatch code review, and inte 1. Run full test suite. Read output. Confirm 0 failures. 2. Run coverage check. Confirm target met with actual numbers. -3. Run `/flow-sync` to ensure spec.md is current. +3. Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` to ensure spec.md is current. 4. If any check fails, report actual results and STOP. ## Phase 3: Code Review diff --git a/templates/opencode/commands/flow-implement.md b/templates/opencode/commands/flow-implement.md index 4ffa1ac..d570440 100644 --- a/templates/opencode/commands/flow-implement.md +++ b/templates/opencode/commands/flow-implement.md @@ -122,7 +122,7 @@ Never force-add ignored Flow artifacts. ### Markdown Sync (Manual) -**CRITICAL:** Do NOT write markers directly to spec.md. It is MANDATORY that you run `/flow-sync` to update the markdown state after any task completion or status change. +**CRITICAL:** Do NOT write markers directly to spec.md. Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` to update the markdown state after task completion or status changes. ### 5.2 Log Learnings diff --git a/templates/opencode/commands/flow-revert.md b/templates/opencode/commands/flow-revert.md index 2709e8a..8a1d6b1 100644 --- a/templates/opencode/commands/flow-revert.md +++ b/templates/opencode/commands/flow-revert.md @@ -41,7 +41,7 @@ bd update {task_id} --status open ### Markdown Sync (Manual) -**CRITICAL:** Do NOT write markers directly to spec.md. It is MANDATORY that you run `/flow-sync` to update the markdown state after any task completion or status change. +**CRITICAL:** Do NOT write markers directly to spec.md. Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` to update the markdown state after task completion or status changes. ## Final Output diff --git a/templates/opencode/commands/flow-revise.md b/templates/opencode/commands/flow-revise.md index abc20e3..a7b2667 100644 --- a/templates/opencode/commands/flow-revise.md +++ b/templates/opencode/commands/flow-revise.md @@ -51,7 +51,7 @@ bd update {new_task_id} --notes "Added during revision. Created by /flow-revise" ### Markdown Sync (Manual) -**CRITICAL:** Do NOT write markers directly to spec.md. It is MANDATORY that you run `/flow-sync` to update the markdown state after any task completion or status change. +**CRITICAL:** Do NOT write markers directly to spec.md. Follow `syncPolicy.flowSyncAfterMutation`; when enabled, run `/flow-sync` to update the markdown state after task completion or status changes. ## Critical Rules diff --git a/templates/opencode/commands/flow-setup.md b/templates/opencode/commands/flow-setup.md index fc65846..8ed71a6 100644 --- a/templates/opencode/commands/flow-setup.md +++ b/templates/opencode/commands/flow-setup.md @@ -60,7 +60,7 @@ else fi ``` -If outdated, suggest the official install: `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash` +If outdated, suggest one of the official installs: `brew install beads`, `npm install -g @beads/bd`, `go install github.com/gastownhall/beads/cmd/bd@latest`, or `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` ### 0.1.2 Knowledge Base Check @@ -140,7 +140,7 @@ If no backend is found, ask user: > Choose a Flow task-memory backend: > -> - **A) Official Beads** (recommended) - Run `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash` +> - **A) Official Beads** (recommended) - Run `brew install beads`, `npm install -g @beads/bd`, `go install github.com/gastownhall/beads/cmd/bd@latest`, or `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash` > - **B) No Beads** - Continue with markdown-only Flow state (reduced memory/resume) If a backend is installed, verify version is current and remember the selected mode for Phase 5. @@ -257,9 +257,14 @@ Based on detected languages, offer relevant styleguides: If official Beads was selected: ```bash -bd init --stealth --prefix +bd init --non-interactive --stealth --prefix --skip-agents +bd config set no-git-ops true +bd config set export.auto false +bd config set export.git-add false ``` +These defaults keep Beads local-only: no automatic export, no auto-staging, and no git operations in `bd prime` output. `bd dolt push` remains explicit opt-in only. + If no-Beads mode was selected: - Skip CLI initialization. @@ -272,7 +277,7 @@ Or prompt user: > - **Local-only** (recommended) - Add local ignores to `.git/info/exclude` > - **Shared repo policy** - Update `.gitignore` for the whole team -Create `/beads.json` with configuration. +Create `/beads.json` with local-only configuration from `templates/agent/beads.json`, including `syncPolicy.allowDoltPush: false`. --- diff --git a/tests/test_beads_policy.py b/tests/test_beads_policy.py new file mode 100644 index 0000000..8cdf903 --- /dev/null +++ b/tests/test_beads_policy.py @@ -0,0 +1,64 @@ +from __future__ import annotations + +import json +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parents[1] + + +def _read(relative_path: str) -> str: + return (REPO_ROOT / relative_path).read_text(encoding="utf-8") + + +def test_default_beads_config_is_local_only_and_manual_export() -> None: + config = json.loads(_read("templates/agent/beads.json")) + + assert config["sync"] == "manual" + assert config["localOnly"] is True + assert config["bdConfig"] == { + "no-git-ops": True, + "export.auto": False, + "export.git-add": False, + } + assert config["syncPolicy"] == { + "flowSyncAfterMutation": True, + "autoExport": False, + "autoGitAdd": False, + "allowDoltPush": False, + } + assert config["dolt"]["push"] == "never" + + +def test_setup_surfaces_apply_beads_no_git_export_defaults() -> None: + for relative_path in ( + "commands/flow/setup.toml", + "commands/flow-setup.md", + "templates/opencode/commands/flow-setup.md", + "skills/flow/references/setup.md", + ): + text = _read(relative_path) + + assert "bd config set no-git-ops true" in text + assert "bd config set export.auto false" in text + assert "bd config set export.git-add false" in text + + +def test_runtime_guidance_requires_config_before_export_or_dolt_push() -> None: + combined = "\n".join( + _read(relative_path) + for relative_path in ( + "AGENTS.md", + "README.md", + "skills/flow/SKILL.md", + "commands/flow-sync.md", + "commands/flow/sync.toml", + "templates/agent/workflow.md", + ) + ) + + assert "syncPolicy" in combined + assert "flowSyncAfterMutation" in combined + assert "allowDoltPush" in combined + assert "bd dolt push" in combined + assert "Do not run `bd dolt push`" in combined diff --git a/tests/test_gemini_plan_mode.py b/tests/test_gemini_plan_mode.py index 000909f..fe1084e 100644 --- a/tests/test_gemini_plan_mode.py +++ b/tests/test_gemini_plan_mode.py @@ -20,7 +20,8 @@ def test_gemini_prd_command_delegates_with_plan_mode() -> None: prompt = _load_command_prompt("commands/flow/prd.toml") assert "enter_plan_mode" in prompt - assert "@flow:prd-orchestrator" in prompt + assert "@prd-orchestrator" in prompt + assert "@flow:" not in prompt def test_gemini_prd_orchestrator_manages_full_plan_mode_lifecycle() -> None: @@ -35,7 +36,15 @@ def test_gemini_plan_command_delegates_with_plan_mode() -> None: prompt = _load_command_prompt("commands/flow/plan.toml") assert "enter_plan_mode" in prompt - assert "@flow:plan-generator" in prompt + assert "@plan-generator" in prompt + assert "@flow:" not in prompt + + +def test_gemini_implement_command_delegates_to_slug_executor() -> None: + prompt = _load_command_prompt("commands/flow/implement.toml") + + assert "@executor" in prompt + assert "@flow:" not in prompt def test_gemini_plan_generator_manages_full_plan_mode_lifecycle() -> None: diff --git a/tests/test_validate_codex_manifest.py b/tests/test_validate_codex_manifest.py new file mode 100644 index 0000000..ffb65fe --- /dev/null +++ b/tests/test_validate_codex_manifest.py @@ -0,0 +1,30 @@ +from __future__ import annotations + +import importlib.util +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parents[1] +MODULE_PATH = REPO_ROOT / "tools" / "validate-codex-manifest.py" + + +def _load_validate_codex_manifest_module(): + spec = importlib.util.spec_from_file_location("validate_codex_manifest", MODULE_PATH) + assert spec is not None + assert spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +validate_codex_manifest = _load_validate_codex_manifest_module() + + +def test_codex_manifest_discovery_excludes_claude_marketplace() -> None: + marketplaces = set(validate_codex_manifest.discover_codex_marketplaces(REPO_ROOT)) + plugin_manifests = set(validate_codex_manifest.discover_codex_plugin_manifests(REPO_ROOT)) + + assert REPO_ROOT / ".agents" / "plugins" / "marketplace.json" in marketplaces + assert REPO_ROOT / ".claude-plugin" / "marketplace.json" not in marketplaces + assert REPO_ROOT / ".codex-plugin" / "plugin.json" in plugin_manifests + assert REPO_ROOT / ".claude-plugin" / "plugin.json" not in plugin_manifests diff --git a/tests/test_validate_skills.py b/tests/test_validate_skills.py index 3c17921..1898358 100644 --- a/tests/test_validate_skills.py +++ b/tests/test_validate_skills.py @@ -208,9 +208,44 @@ def test_shared_hook_config_allows_cross_host_fallback_command(tmp_path: Path) - assert validate_skills.validate_gemini_hook_config(hooks_path) == [] -def test_repo_cursor_and_codex_manifests_still_validate() -> None: - cursor_violations = validate_skills.validate_manifest(REPO_ROOT / ".cursor-plugin" / "plugin.json") +def test_makefile_recipes_fail_fast() -> None: + makefile = (REPO_ROOT / "Makefile").read_text(encoding="utf-8") + + assert ".SHELLFLAGS" in makefile + assert "-e" in makefile + assert "-o pipefail" in makefile + assert "validate-codex-manifest:" in makefile + assert "check: lint validate-skills validate-codex-manifest sync-manifests" in makefile + + +def test_repo_uses_supported_cursor_surface() -> None: + assert not (REPO_ROOT / ".cursor-plugin" / "plugin.json").exists() + assert (REPO_ROOT / ".cursor" / "rules" / "flow.mdc").is_file() + + +def test_repo_host_native_agent_surfaces_validate() -> None: + expected = {"code-reviewer", "executor", "plan-generator", "prd-orchestrator"} + + assert {path.stem for path in validate_skills.iter_gemini_agents()} == expected + assert {path.stem for path in validate_skills.iter_codex_agents()} == expected + assert {path.stem for path in validate_skills.iter_opencode_agents()} == expected + assert {path.stem.removesuffix(".agent") for path in validate_skills.iter_vscode_agents()} == expected + + violations = [] + for agent_path in validate_skills.iter_gemini_agents(): + violations.extend(validate_skills.validate_gemini_agent(agent_path)) + violations.extend(validate_skills.validate_claude_agent(agent_path)) + for agent_path in validate_skills.iter_codex_agents(): + violations.extend(validate_skills.validate_codex_agent(agent_path)) + for agent_path in validate_skills.iter_opencode_agents(): + violations.extend(validate_skills.validate_opencode_agent(agent_path)) + for agent_path in validate_skills.iter_vscode_agents(): + violations.extend(validate_skills.validate_vscode_agent(agent_path)) + + assert violations == [] + + +def test_repo_codex_manifest_validates() -> None: codex_violations = validate_skills.validate_manifest(REPO_ROOT / ".codex-plugin" / "plugin.json") - assert cursor_violations == [] assert codex_violations == [] diff --git a/tools/install.sh b/tools/install.sh index 46985e5..9f9696a 100755 --- a/tools/install.sh +++ b/tools/install.sh @@ -46,7 +46,7 @@ show_banner() { echo -e "${CYAN}" echo "╔══════════════════════════════════════════════════════════════╗" echo "║ Flow Framework - Plugin Installer ║" - echo "║ Version 0.20.0 ║" + echo "║ Version 0.20.1 ║" echo "╚══════════════════════════════════════════════════════════════╝" echo -e "${NC}" @@ -496,7 +496,8 @@ check_beads() { local version version=$(bd --version 2>/dev/null || echo "unknown") log_success "Official Beads (bd) installed: $version" - log_info "Flow setup will default to: bd init --stealth --prefix " + log_info "Flow setup will default to: bd init --non-interactive --stealth --prefix --skip-agents" + log_info "Flow setup will also set: bd config set no-git-ops true; bd config set export.auto false; bd config set export.git-add false" if command -v br &>/dev/null; then log_warn "Legacy br (beads_rust) detected alongside bd. Flow no longer uses br; you can uninstall it." fi @@ -514,11 +515,14 @@ check_beads() { echo " 1) Install official Beads (bd) (recommended)" echo " 2) Continue without Beads" echo "" + echo "Official install options: brew install beads, npm install -g @beads/bd," + echo "go install github.com/gastownhall/beads/cmd/bd@latest, or the installer script." + echo "" read -p "Select [1-2]: " -n 1 -r echo case $REPLY in 1) - curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash + curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash log_success "Installed official Beads (bd)" log_info "Flow setup defaults to repo-slug prefixes and prefers .git/info/exclude for local-only artifacts" ;; diff --git a/tools/validate-codex-manifest.py b/tools/validate-codex-manifest.py index 1d580ee..eb681e9 100755 --- a/tools/validate-codex-manifest.py +++ b/tools/validate-codex-manifest.py @@ -4,13 +4,16 @@ """ import json -import os -import sys import re +import sys +from collections.abc import Iterator +from pathlib import Path + -def validate_marketplace(file_path): +def validate_marketplace(file_path: str | Path): + file_path = Path(file_path) print(f"Validating marketplace: {file_path}") - with open(file_path, 'r') as f: + with file_path.open() as f: try: data = json.load(f) except json.JSONDecodeError as e: @@ -22,10 +25,10 @@ def validate_marketplace(file_path): for plugin in plugins: name = plugin.get('name', 'unknown') source_field = plugin.get('source', {}) - + path = "" is_local = False - + if isinstance(source_field, str): path = source_field is_local = True @@ -39,7 +42,7 @@ def validate_marketplace(file_path): if not path.startswith('./'): print(f" ERROR [plugin {name}]: path '{path}' must start with './'") errors += 1 - + # 2. Must not be empty (after stripping ./) normalized = path[2:] if path.startswith('./') else path if not normalized or normalized.strip('/') == '': @@ -50,12 +53,14 @@ def validate_marketplace(file_path): if '..' in path: print(f" ERROR [plugin {name}]: path '{path}' must not contain '..'") errors += 1 - + return errors == 0 -def validate_plugin_manifest(file_path): + +def validate_plugin_manifest(file_path: str | Path): + file_path = Path(file_path) print(f"Validating plugin manifest: {file_path}") - with open(file_path, 'r') as f: + with file_path.open() as f: try: data = json.load(f) except json.JSONDecodeError as e: @@ -69,23 +74,39 @@ def validate_plugin_manifest(file_path): if not re.match(r'^[a-z][a-zA-Z0-9]*$', key): print(f" ERROR [userConfig]: key '{key}' must be camelCase (no hyphens or underscores)") errors += 1 - + return errors == 0 + +def discover_codex_marketplaces(root: str | Path = ".") -> Iterator[Path]: + """Yield Codex marketplace manifests only.""" + root_path = Path(root) + candidate = root_path / ".agents" / "plugins" / "marketplace.json" + if candidate.is_file(): + yield candidate + + +def discover_codex_plugin_manifests(root: str | Path = ".") -> Iterator[Path]: + """Yield Codex plugin manifests, excluding other hosts' plugin.json files.""" + root_path = Path(root) + root_manifest = root_path / ".codex-plugin" / "plugin.json" + if root_manifest.is_file(): + yield root_manifest + agents_plugins = root_path / ".agents" / "plugins" / "plugins" + if agents_plugins.is_dir(): + yield from sorted(agents_plugins.glob("*/.codex-plugin/plugin.json")) + + def main(): success = True - - # Find all marketplace.json files - for root, _, files in os.walk('.'): - if 'marketplace.json' in files: - path = os.path.join(root, 'marketplace.json') - if not validate_marketplace(path): - success = False - - if 'plugin.json' in files: - path = os.path.join(root, 'plugin.json') - if not validate_plugin_manifest(path): - success = False + + for path in discover_codex_marketplaces(): + if not validate_marketplace(path): + success = False + + for path in discover_codex_plugin_manifests(): + if not validate_plugin_manifest(path): + success = False if not success: print("\nValidation failed!") diff --git a/tools/validate-skills.py b/tools/validate-skills.py index b064367..c2999d3 100644 --- a/tools/validate-skills.py +++ b/tools/validate-skills.py @@ -13,9 +13,8 @@ resolves relative to the file. * ``commands/**/*.toml`` parses as TOML and has top-level ``description`` (str, <= 1024 chars) and ``prompt`` (non-empty str). -* ``agents/*.md`` frontmatter has ``name`` matching filename, ``description`` - (<= 1024 chars), ``mode`` in {subagent, primary}, and ``tools`` mapping with - whitelisted keys and bool values. +* ``agents/*.md``, ``.codex/agents/*.toml``, ``.opencode/agents/*.md``, and + ``.github/agents/*.agent.md`` use host-native subagent schemas. * Shipped content (skills, commands, agents, and the root ``AGENTS.md`` / ``CONTRIBUTING.md`` / ``README.md`` / ``GEMINI.md``) contains no references to the framework authoring tree — except the user-install convention path @@ -61,6 +60,7 @@ def _toml_loads(text: str) -> dict[str, Any]: # `agents/` at repo root is Gemini CLI's extension subagents directory. # `.opencode/agents/` is OpenCode's project-scoped subagents directory. # `.claude-plugin/agents/` is Claude Code's plugin subagents directory. +# `.github/agents/` is VS Code / Copilot's workspace custom agent directory. # All three hosts use incompatible frontmatter schemas, so each location is # validated by its own rules (see `validate_gemini_agent` / # `validate_opencode_agent` / `validate_claude_agent`). @@ -68,6 +68,7 @@ def _toml_loads(text: str) -> dict[str, Any]: OPENCODE_AGENTS_DIR = REPO_ROOT / ".opencode" / "agents" CLAUDE_AGENTS_DIR = REPO_ROOT / ".claude-plugin" / "agents" CODEX_AGENTS_DIR = REPO_ROOT / ".codex" / "agents" +VSCODE_AGENTS_DIR = REPO_ROOT / ".github" / "agents" SHIPPED_ROOT_FILES = ("AGENTS.md", "CONTRIBUTING.md", "README.md", "GEMINI.md") MAX_DESCRIPTION_CHARS = 1024 @@ -170,6 +171,7 @@ def _toml_loads(text: str) -> dict[str, Any]: # Codex nickname_candidates entries: ASCII letters, digits, spaces, hyphens, # underscores only. Per https://developers.openai.com/codex/subagents. _CODEX_NICKNAME_PATTERN = re.compile(r"^[A-Za-z0-9 _-]+$") +_AGENT_REFERENCE_PATTERN = re.compile(r"@([A-Za-z][A-Za-z0-9:_-]*)") class Violation(NamedTuple): @@ -546,6 +548,72 @@ def validate_claude_agent(path: Path) -> list[Violation]: return violations +def validate_vscode_agent(path: Path) -> list[Violation]: + """Validate a VS Code / Copilot custom agent file. + + VS Code discovers workspace agents from ``.github/agents/*.agent.md``. + The frontmatter may be minimal; Flow requires explicit ``name`` and + ``description`` so the same agent identity is testable across hosts. + """ + violations: list[Violation] = [] + if not path.name.endswith(".agent.md"): + violations.append(Violation(path, 1, "VS Code custom agents must use the .agent.md extension")) + text = path.read_text(encoding="utf-8") + try: + fm, _body_start, _body = extract_frontmatter(text) + except ValueError as exc: + return [Violation(path, 1, str(exc))] + expected_name = path.name.removesuffix(".agent.md") + if fm.get("name") != expected_name: + violations.append(Violation(path, 1, f"name {fm.get('name')!r} != filename stem {expected_name!r}")) + violations.extend(_check_description(fm.get("description"), path, 1)) + tools = fm.get("tools") + if tools is not None: + if not isinstance(tools, list): + violations.append(Violation(path, 1, "tools must be a list when present")) + else: + for entry in cast("list[Any]", tools): # type: ignore[redundant-cast] + if not isinstance(entry, str) or not entry.strip(): + violations.append(Violation(path, 1, "tools entries must be non-empty strings")) + agents = fm.get("agents") + if agents is not None: + if agents != "*" and not isinstance(agents, list): + violations.append(Violation(path, 1, "agents must be '*' or a list when present")) + elif isinstance(agents, list): + for entry in cast("list[Any]", agents): # type: ignore[redundant-cast] + if not isinstance(entry, str) or not entry.strip(): + violations.append(Violation(path, 1, "agents entries must be non-empty strings")) + return violations + + +def validate_command_agent_references(path: Path) -> list[Violation]: + """Validate Flow command prompts reference shipped agents by slug. + + Gemini's subagent mention syntax uses the slug from ``agents/.md``. + Namespaced mentions like ``@flow:executor`` are invalid for the shipped + root ``agents/`` bundle. + """ + violations: list[Violation] = [] + try: + data = _toml_loads(path.read_text(encoding="utf-8")) + except _TOMLDecodeError as exc: + return [Violation(path, 1, f"TOML parse error: {exc}")] + prompt = data.get("prompt") + if not isinstance(prompt, str): + return violations + known_agents = {agent_path.stem for agent_path in iter_gemini_agents()} + for match in _AGENT_REFERENCE_PATTERN.finditer(prompt): + mention = match.group(1) + if mention.startswith("flow:"): + violations.append( + Violation(path, 1, f"agent mention '@{mention}' must use the slug without the flow: namespace") + ) + continue + if mention in {"code-reviewer", "executor", "plan-generator", "prd-orchestrator"} and mention not in known_agents: + violations.append(Violation(path, 1, f"agent mention '@{mention}' has no matching agents/{mention}.md")) + return violations + + def validate_manifest(path: Path) -> list[Violation]: """Validate a host-specific plugin.json manifest. @@ -741,8 +809,37 @@ def iter_opencode_agents() -> Iterator[Path]: def iter_claude_agents() -> Iterator[Path]: + seen: set[Path] = set() if CLAUDE_AGENTS_DIR.is_dir(): - yield from sorted(CLAUDE_AGENTS_DIR.glob("*.md")) + for path in sorted(CLAUDE_AGENTS_DIR.glob("*.md")): + resolved = path.resolve() + seen.add(resolved) + yield path + + manifest_path = REPO_ROOT / ".claude-plugin" / "plugin.json" + if not manifest_path.is_file(): + return + try: + data = json.loads(manifest_path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError): + return + agents = data.get("agents") if isinstance(data, dict) else None + if isinstance(agents, str): + agent_paths: Iterable[str] = (agents,) + elif isinstance(agents, list): + agent_paths = (entry for entry in agents if isinstance(entry, str)) + else: + return + for raw_path in agent_paths: + resolved, error = _resolve_plugin_path(manifest_path, raw_path) + if error is not None or resolved is None or not resolved.is_dir(): + continue + for path in sorted(resolved.glob("*.md")): + real = path.resolve() + if real in seen: + continue + seen.add(real) + yield path def iter_codex_agents() -> Iterator[Path]: @@ -750,8 +847,13 @@ def iter_codex_agents() -> Iterator[Path]: yield from sorted(CODEX_AGENTS_DIR.glob("*.toml")) +def iter_vscode_agents() -> Iterator[Path]: + if VSCODE_AGENTS_DIR.is_dir(): + yield from sorted(VSCODE_AGENTS_DIR.glob("*.agent.md")) + + def iter_manifests() -> Iterator[Path]: - for host in (".claude-plugin", ".codex-plugin", ".cursor-plugin"): + for host in (".claude-plugin", ".codex-plugin"): candidate = REPO_ROOT / host / "plugin.json" if candidate.is_file(): yield candidate @@ -801,6 +903,11 @@ def iter_all_shipped_files() -> Iterator[Path]: yield from sorted(CLAUDE_AGENTS_DIR.rglob("*.md")) if CODEX_AGENTS_DIR.is_dir(): yield from sorted(CODEX_AGENTS_DIR.rglob("*.toml")) + if VSCODE_AGENTS_DIR.is_dir(): + yield from sorted(VSCODE_AGENTS_DIR.rglob("*.md")) + cursor_rules_dir = REPO_ROOT / ".cursor" / "rules" + if cursor_rules_dir.is_dir(): + yield from sorted(cursor_rules_dir.rglob("*.mdc")) for name in SHIPPED_ROOT_FILES: candidate = REPO_ROOT / name if candidate.is_file(): @@ -835,6 +942,7 @@ def main() -> int: opencode_agents = list(iter_opencode_agents()) claude_agents = list(iter_claude_agents()) codex_agents = list(iter_codex_agents()) + vscode_agents = list(iter_vscode_agents()) manifests = list(iter_manifests()) claude_hook_configs = list(iter_claude_hook_configs()) gemini_hook_configs = list(iter_gemini_hook_configs()) @@ -844,6 +952,7 @@ def main() -> int: all_violations.extend(validate_skill(skill_path)) for cmd_path in commands: all_violations.extend(validate_command(cmd_path)) + all_violations.extend(validate_command_agent_references(cmd_path)) for agent_path in gemini_agents: all_violations.extend(validate_gemini_agent(agent_path)) for agent_path in opencode_agents: @@ -852,6 +961,8 @@ def main() -> int: all_violations.extend(validate_claude_agent(agent_path)) for agent_path in codex_agents: all_violations.extend(validate_codex_agent(agent_path)) + for agent_path in vscode_agents: + all_violations.extend(validate_vscode_agent(agent_path)) for hook_config_path in claude_hook_configs: all_violations.extend(validate_claude_hook_config(hook_config_path)) for hook_config_path in gemini_hook_configs: @@ -863,7 +974,7 @@ def main() -> int: _print_violations(all_violations) print(f"\n{len(all_violations)} violation(s)", file=sys.stderr) return 1 - agent_total = len(gemini_agents) + len(opencode_agents) + len(claude_agents) + len(codex_agents) + agent_total = len(gemini_agents) + len(opencode_agents) + len(claude_agents) + len(codex_agents) + len(vscode_agents) print(f"[ OK ] validated {len(skills)} skills, {len(commands)} commands, {agent_total} agents — no violations") return 0 diff --git a/uv.lock b/uv.lock index 304bc55..5c56a34 100644 --- a/uv.lock +++ b/uv.lock @@ -189,7 +189,7 @@ toml = [ [[package]] name = "flow" -version = "0.20.0" +version = "0.20.1" source = { virtual = "." } [package.optional-dependencies] From a199413b45388a4af8ee7e43a0e9a55b8017d55a Mon Sep 17 00:00:00 2001 From: Cody Fincher Date: Sun, 26 Apr 2026 22:46:56 +0000 Subject: [PATCH 2/3] fix(ci): install dev extras for validation --- .github/workflows/check.yml | 2 +- .github/workflows/release.yml | 2 +- Makefile | 10 +++++----- tests/test_ci_config.py | 24 ++++++++++++++++++++++++ 4 files changed, 31 insertions(+), 7 deletions(-) create mode 100644 tests/test_ci_config.py diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 5af1954..d470dbc 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -31,7 +31,7 @@ jobs: - name: Install dependencies run: | - uv sync --dev + uv sync --extra dev - name: Set up Node.js uses: actions/setup-node@v4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 445fc13..c981be7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,7 +25,7 @@ jobs: enable-cache: true - name: Validate shipped manifests - run: uv run tools/validate-skills.py + run: uv run --extra dev tools/validate-skills.py - name: Build package run: make build diff --git a/Makefile b/Makefile index e626853..a480af2 100644 --- a/Makefile +++ b/Makefile @@ -53,19 +53,19 @@ lint: ## Lint and auto-fix all mar .PHONY: validate-skills validate-skills: ## Validate skill / command / agent manifests @echo "${INFO} Validating skill manifests..." - @uv run tools/validate-skills.py + @uv run --extra dev tools/validate-skills.py @echo "${OK} Skill manifests valid" .PHONY: validate-codex-manifest validate-codex-manifest: ## Validate Codex marketplace and plugin manifests @echo "${INFO} Validating Codex manifests..." - @uv run tools/validate-codex-manifest.py + @uv run --extra dev tools/validate-codex-manifest.py @echo "${OK} Codex manifests valid" .PHONY: sync-manifests sync-manifests: ## Sync version strings across all manifests @echo "${INFO} Syncing version strings..." - @uv run tools/sync-manifests.py + @uv run --extra dev tools/sync-manifests.py @echo "${OK} Version strings in sync" .PHONY: check @@ -81,7 +81,7 @@ build: ## Build the package release: ## Bump version and create release tag (e.g. make release bump=patch) @echo "${INFO} Preparing for release... 📦" @make clean - @uv run bump-my-version bump $(bump) + @uv run --extra dev bump-my-version bump $(bump) @make build @echo "${OK} Release complete 🎉" @@ -89,6 +89,6 @@ release: ## Bump version and create re pre-release: ## Start/advance a pre-release (e.g. make pre-release version=1.1.0a1) @echo "${INFO} Preparing pre-release $(version)... 📦" @make clean - @uv run bump-my-version bump --new-version $(version) patch + @uv run --extra dev bump-my-version bump --new-version $(version) patch @make build @echo "${OK} Pre-release $(version) complete 🎉" diff --git a/tests/test_ci_config.py b/tests/test_ci_config.py new file mode 100644 index 0000000..a717cf5 --- /dev/null +++ b/tests/test_ci_config.py @@ -0,0 +1,24 @@ +from __future__ import annotations + +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parents[1] + + +def _read(relative_path: str) -> str: + return (REPO_ROOT / relative_path).read_text(encoding="utf-8") + + +def test_makefile_python_tool_targets_use_dev_extra() -> None: + makefile = _read("Makefile") + + assert "uv run --extra dev tools/validate-skills.py" in makefile + assert "uv run --extra dev tools/validate-codex-manifest.py" in makefile + assert "uv run --extra dev tools/sync-manifests.py" in makefile + + +def test_quality_workflow_installs_dev_extra() -> None: + workflow = _read(".github/workflows/check.yml") + + assert "uv sync --extra dev" in workflow From 086d92418a05ed8a9bd931abe2b0700bb48c85dc Mon Sep 17 00:00:00 2001 From: Cody Fincher Date: Sun, 26 Apr 2026 23:06:43 +0000 Subject: [PATCH 3/3] feat(skills): optimize trigger metadata --- .codex-plugin/plugin.json | 8 +- .cursor/rules/flow.mdc | 2 + .opencode/plugins/flow.js | 2 + AGENTS.md | 2 + CLAUDE.md | 2 + GEMINI.md | 2 + commands/flow-archive.md | 2 + commands/flow-docs.md | 2 + commands/flow-finish.md | 2 + commands/flow-implement.md | 2 + commands/flow-plan.md | 2 + commands/flow-prd.md | 2 + commands/flow-refine.md | 2 + commands/flow-refresh.md | 2 + commands/flow-research.md | 2 + commands/flow-revert.md | 2 + commands/flow-review.md | 2 + commands/flow-revise.md | 2 + commands/flow-setup.md | 2 + commands/flow-status.md | 2 + commands/flow-sync.md | 2 + commands/flow-task.md | 2 + commands/flow-validate.md | 2 + commands/flow/archive.toml | 3 + commands/flow/cleanup.toml | 3 + commands/flow/docs.toml | 3 + commands/flow/finish.toml | 3 + commands/flow/implement.toml | 3 + commands/flow/plan.toml | 3 + commands/flow/prd.toml | 3 + commands/flow/refine.toml | 3 + commands/flow/refresh.toml | 3 + commands/flow/research.toml | 3 + commands/flow/revert.toml | 3 + commands/flow/review.toml | 3 + commands/flow/revise.toml | 3 + commands/flow/setup.toml | 3 + commands/flow/status.toml | 3 + commands/flow/sync.toml | 3 + commands/flow/task.toml | 3 + commands/flow/validate.toml | 3 + skills/alloydb-omni/SKILL.md | 2 +- skills/alloydb-omni/agents/openai.yaml | 3 + skills/alloydb/SKILL.md | 2 +- skills/alloydb/agents/openai.yaml | 3 + skills/angular/SKILL.md | 2 +- skills/angular/agents/openai.yaml | 3 + skills/apilookup/SKILL.md | 2 +- skills/apilookup/agents/openai.yaml | 3 + skills/architecture-critic/SKILL.md | 2 +- skills/architecture-critic/agents/openai.yaml | 3 + skills/bash/SKILL.md | 2 +- skills/bash/agents/openai.yaml | 3 + skills/biome/SKILL.md | 2 +- skills/biome/agents/openai.yaml | 3 + skills/bun/SKILL.md | 2 +- skills/bun/agents/openai.yaml | 3 + skills/challenge/SKILL.md | 2 +- skills/challenge/agents/openai.yaml | 3 + skills/cloud-run/SKILL.md | 2 +- skills/cloud-run/agents/openai.yaml | 3 + skills/cloud-sql/SKILL.md | 2 +- skills/cloud-sql/agents/openai.yaml | 3 + skills/consensus/SKILL.md | 2 +- skills/consensus/agents/openai.yaml | 3 + skills/cpp/SKILL.md | 2 +- skills/cpp/agents/openai.yaml | 2 +- skills/deepthink/SKILL.md | 2 +- skills/deepthink/agents/openai.yaml | 3 + skills/devils-advocate/SKILL.md | 2 +- skills/devils-advocate/agents/openai.yaml | 3 + skills/dishka/SKILL.md | 2 +- skills/dishka/agents/openai.yaml | 3 + skills/docgen/SKILL.md | 2 +- skills/docgen/agents/openai.yaml | 3 + skills/docker/SKILL.md | 2 +- skills/docker/agents/openai.yaml | 3 + skills/duckdb/SKILL.md | 2 +- skills/duckdb/agents/openai.yaml | 3 + skills/flow-completion/SKILL.md | 45 +++ skills/flow-completion/agents/openai.yaml | 3 + skills/flow-execution/SKILL.md | 40 ++ skills/flow-execution/agents/openai.yaml | 3 + skills/flow-planning/SKILL.md | 44 +++ skills/flow-planning/agents/openai.yaml | 3 + skills/flow-setup/SKILL.md | 41 +++ skills/flow-setup/agents/openai.yaml | 3 + skills/flow-sync-status/SKILL.md | 42 +++ skills/flow-sync-status/agents/openai.yaml | 3 + skills/flow/SKILL.md | 348 ++---------------- skills/flow/agents/openai.yaml | 2 +- skills/gcp/SKILL.md | 2 +- skills/gcp/agents/openai.yaml | 3 + skills/gke/SKILL.md | 2 +- skills/gke/agents/openai.yaml | 3 + skills/granian/SKILL.md | 2 +- skills/granian/agents/openai.yaml | 3 + skills/htmx/SKILL.md | 2 +- skills/htmx/agents/openai.yaml | 3 + skills/inertia/SKILL.md | 2 +- skills/inertia/agents/openai.yaml | 3 + skills/integrating-agent-platforms/SKILL.md | 2 +- .../agents/openai.yaml | 3 + skills/ipc/SKILL.md | 2 +- skills/ipc/agents/openai.yaml | 3 + skills/makefile/SKILL.md | 2 +- skills/makefile/agents/openai.yaml | 3 + skills/mojo-tools/SKILL.md | 2 +- skills/mojo-tools/agents/openai.yaml | 3 + skills/mysql/SKILL.md | 2 +- skills/mysql/agents/openai.yaml | 3 + skills/nuxt/SKILL.md | 2 +- skills/nuxt/agents/openai.yaml | 3 + skills/oracle/SKILL.md | 2 +- skills/oracle/agents/openai.yaml | 3 + skills/performance-analyst/SKILL.md | 2 +- skills/performance-analyst/agents/openai.yaml | 3 + skills/perspectives/SKILL.md | 2 +- skills/perspectives/agents/openai.yaml | 3 + skills/podman/SKILL.md | 2 +- skills/podman/agents/openai.yaml | 3 + skills/postgres/SKILL.md | 2 +- skills/postgres/agents/openai.yaml | 3 + skills/pyapp/SKILL.md | 2 +- skills/pyapp/agents/openai.yaml | 3 + skills/pydantic/SKILL.md | 2 +- skills/pydantic/agents/openai.yaml | 3 + skills/python/SKILL.md | 2 +- skills/python/agents/openai.yaml | 3 + skills/railway-tools/SKILL.md | 2 +- skills/railway-tools/agents/openai.yaml | 3 + skills/react/SKILL.md | 2 +- skills/react/agents/openai.yaml | 3 + skills/rust/SKILL.md | 2 +- skills/rust/agents/openai.yaml | 3 + skills/saq/SKILL.md | 2 +- skills/saq/agents/openai.yaml | 3 + skills/security-auditor/SKILL.md | 2 +- skills/security-auditor/agents/openai.yaml | 3 + skills/shadcn-tools/SKILL.md | 2 +- skills/shadcn-tools/agents/openai.yaml | 3 + skills/sphinx/SKILL.md | 2 +- skills/sphinx/agents/openai.yaml | 3 + skills/sqlalchemy/SKILL.md | 2 +- skills/sqlalchemy/agents/openai.yaml | 3 + skills/sqlserver/SKILL.md | 2 +- skills/sqlserver/agents/openai.yaml | 3 + skills/svelte/SKILL.md | 2 +- skills/svelte/agents/openai.yaml | 3 + skills/tailwind/SKILL.md | 2 +- skills/tailwind/agents/openai.yaml | 3 + skills/tanstack/SKILL.md | 2 +- skills/tanstack/agents/openai.yaml | 3 + skills/terraform/SKILL.md | 2 +- skills/terraform/agents/openai.yaml | 3 + skills/testing/SKILL.md | 2 +- skills/testing/agents/openai.yaml | 3 + skills/tracer/SKILL.md | 2 +- skills/tracer/agents/openai.yaml | 3 + skills/uvicorn/SKILL.md | 2 +- skills/uvicorn/agents/openai.yaml | 3 + skills/vite/SKILL.md | 2 +- skills/vite/agents/openai.yaml | 3 + skills/vue/SKILL.md | 2 +- skills/vue/agents/openai.yaml | 3 + tests/test_validate_skills.py | 78 ++++ tools/validate-skills.py | 59 ++- 167 files changed, 720 insertions(+), 379 deletions(-) create mode 100644 skills/alloydb-omni/agents/openai.yaml create mode 100644 skills/alloydb/agents/openai.yaml create mode 100644 skills/angular/agents/openai.yaml create mode 100644 skills/apilookup/agents/openai.yaml create mode 100644 skills/architecture-critic/agents/openai.yaml create mode 100644 skills/bash/agents/openai.yaml create mode 100644 skills/biome/agents/openai.yaml create mode 100644 skills/bun/agents/openai.yaml create mode 100644 skills/challenge/agents/openai.yaml create mode 100644 skills/cloud-run/agents/openai.yaml create mode 100644 skills/cloud-sql/agents/openai.yaml create mode 100644 skills/consensus/agents/openai.yaml create mode 100644 skills/deepthink/agents/openai.yaml create mode 100644 skills/devils-advocate/agents/openai.yaml create mode 100644 skills/dishka/agents/openai.yaml create mode 100644 skills/docgen/agents/openai.yaml create mode 100644 skills/docker/agents/openai.yaml create mode 100644 skills/duckdb/agents/openai.yaml create mode 100644 skills/flow-completion/SKILL.md create mode 100644 skills/flow-completion/agents/openai.yaml create mode 100644 skills/flow-execution/SKILL.md create mode 100644 skills/flow-execution/agents/openai.yaml create mode 100644 skills/flow-planning/SKILL.md create mode 100644 skills/flow-planning/agents/openai.yaml create mode 100644 skills/flow-setup/SKILL.md create mode 100644 skills/flow-setup/agents/openai.yaml create mode 100644 skills/flow-sync-status/SKILL.md create mode 100644 skills/flow-sync-status/agents/openai.yaml create mode 100644 skills/gcp/agents/openai.yaml create mode 100644 skills/gke/agents/openai.yaml create mode 100644 skills/granian/agents/openai.yaml create mode 100644 skills/htmx/agents/openai.yaml create mode 100644 skills/inertia/agents/openai.yaml create mode 100644 skills/integrating-agent-platforms/agents/openai.yaml create mode 100644 skills/ipc/agents/openai.yaml create mode 100644 skills/makefile/agents/openai.yaml create mode 100644 skills/mojo-tools/agents/openai.yaml create mode 100644 skills/mysql/agents/openai.yaml create mode 100644 skills/nuxt/agents/openai.yaml create mode 100644 skills/oracle/agents/openai.yaml create mode 100644 skills/performance-analyst/agents/openai.yaml create mode 100644 skills/perspectives/agents/openai.yaml create mode 100644 skills/podman/agents/openai.yaml create mode 100644 skills/postgres/agents/openai.yaml create mode 100644 skills/pyapp/agents/openai.yaml create mode 100644 skills/pydantic/agents/openai.yaml create mode 100644 skills/python/agents/openai.yaml create mode 100644 skills/railway-tools/agents/openai.yaml create mode 100644 skills/react/agents/openai.yaml create mode 100644 skills/rust/agents/openai.yaml create mode 100644 skills/saq/agents/openai.yaml create mode 100644 skills/security-auditor/agents/openai.yaml create mode 100644 skills/shadcn-tools/agents/openai.yaml create mode 100644 skills/sphinx/agents/openai.yaml create mode 100644 skills/sqlalchemy/agents/openai.yaml create mode 100644 skills/sqlserver/agents/openai.yaml create mode 100644 skills/svelte/agents/openai.yaml create mode 100644 skills/tailwind/agents/openai.yaml create mode 100644 skills/tanstack/agents/openai.yaml create mode 100644 skills/terraform/agents/openai.yaml create mode 100644 skills/testing/agents/openai.yaml create mode 100644 skills/tracer/agents/openai.yaml create mode 100644 skills/uvicorn/agents/openai.yaml create mode 100644 skills/vite/agents/openai.yaml create mode 100644 skills/vue/agents/openai.yaml diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index dfd72b9..4449bb0 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -14,10 +14,10 @@ "category": "Development", "capabilities": ["Read", "Write"], "defaultPrompt": [ - "Use the Flow skill to set up this project", - "Use the Flow skill to create a PRD for user authentication", - "Use the Flow skill to refine this spec into implementation-ready tasks", - "Use the Flow skill to implement the current flow with TDD and verification" + "Use the Flow router and flow-setup to set up this project", + "Use the Flow router and flow-planning to create a PRD for user authentication", + "Use the Flow router and flow-planning to refine this spec into implementation-ready tasks", + "Use the Flow router and flow-execution to implement the current flow with TDD and verification" ] } } diff --git a/.cursor/rules/flow.mdc b/.cursor/rules/flow.mdc index e8be117..c837301 100644 --- a/.cursor/rules/flow.mdc +++ b/.cursor/rules/flow.mdc @@ -5,4 +5,6 @@ alwaysApply: true When a repository has `.agents/`, use the Flow workflow for planning, implementation, sync, status, review, finish, archive, and Beads-backed task memory. +After the `flow` router skill triggers, load the matching lifecycle skill: `flow-setup`, `flow-planning`, `flow-execution`, `flow-sync-status`, or `flow-completion`. + Prefer the installed Flow skills and the repository `AGENTS.md` instructions. Do not rely on a repository `.cursor-plugin/plugin.json`; Cursor consumes rules and project instructions from its supported customization surfaces. diff --git a/.opencode/plugins/flow.js b/.opencode/plugins/flow.js index ee16bdc..5f85473 100644 --- a/.opencode/plugins/flow.js +++ b/.opencode/plugins/flow.js @@ -56,10 +56,12 @@ function buildSessionContext() { '- When user says "implement", "plan", "spec", "prd", "sync", "status": immediately invoke the matching Flow workflow rather than staying in generic chat mode', '- When editing files in .agents/specs/: invoke flow skill for context', '- When user mentions "beads", "bd", or backend migration: invoke flow skill', + '- Route lifecycle detail through flow-setup, flow-planning, flow-execution, flow-sync-status, or flow-completion after the flow router skill triggers', '- When a spec or PRD exists but task detail is coarse: invoke flow-refine before implementation or subagent dispatch', '- Do not finish PRD or planning work while obvious research gaps remain', '', 'Key commands: /flow:setup, /flow:prd, /flow:plan, /flow:implement, /flow:sync, /flow:status, /flow:refresh', + 'Lifecycle skills: flow-setup, flow-planning, flow-execution, flow-sync-status, flow-completion.', '', 'All spec/design docs go in .agents/specs/ (not docs/superpowers/specs/).', 'Before dispatching subagents, preserve context with the relevant spec/PRD, patterns, knowledge chapters, learnings, affected files, and verification requirements.', diff --git a/AGENTS.md b/AGENTS.md index 36fc58f..3ced1a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -196,6 +196,8 @@ The following external repositories provide comprehensive, host-verified skills **Host note:** Gemini CLI and OpenCode expose these as `/flow:*`. Claude Code uses `/flow-*`. Codex currently runs the same workflows through the installed Flow skill and plain-language requests rather than plugin-defined slash commands. +**Lifecycle routing:** Keep `flow` as the small router skill. After it triggers, load the specific lifecycle skill: `flow-setup` for initialization and validation, `flow-planning` for PRD/spec/refine/revise/research/task work, `flow-execution` for implementation and TDD, `flow-sync-status` for sync/status/refresh/cleanup, and `flow-completion` for review/finish/archive/revert/docs. + | Command | Purpose | |---------|---------| | `/flow:setup` | Initialize project with context files, Beads, and first flow | diff --git a/CLAUDE.md b/CLAUDE.md index fbd5fa0..b8f5eb7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,7 @@ Use Flow when the user asks to: When Flow planning is active: +- route setup work through `flow-setup`, PRD/spec/refine work through `flow-planning`, implementation through `flow-execution`, sync/status through `flow-sync-status`, and review/finish/archive work through `flow-completion` - automatically use the matching Flow workflow instead of staying in generic chat mode - keep the workflow in research/planning mode while researching, questioning, drafting, and revising planning artifacts - refine coarse tasks before implementation so lighter-weight executors do not have to guess @@ -30,6 +31,7 @@ When Flow planning is active: When Flow implementation is active: +- load `flow-execution` after the `flow` router skill so the monolithic Flow skill does not carry implementation-only detail into unrelated requests - read `.agents/workflow.md` and prefer the repo's canonical commands for setup, lint, test, typecheck, and full verification - preserve context for subagents with `spec.md`, parent PRD context, `patterns.md`, relevant `knowledge/` chapters, `learnings.md`, affected files, and verification requirements - prefer refined tasks before dispatching lighter-weight agents diff --git a/GEMINI.md b/GEMINI.md index bf81239..c7ee3ca 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -22,6 +22,7 @@ Use Flow when the user asks to: When Flow planning is active: +- route setup work through `flow-setup`, PRD/spec/refine work through `flow-planning`, implementation through `flow-execution`, sync/status through `flow-sync-status`, and review/finish/archive work through `flow-completion` - automatically use the matching Flow workflow instead of staying in generic chat mode - if not already in Plan Mode, call `enter_plan_mode` before starting `/flow:prd` or `/flow:plan` - keep the workflow in Plan Mode while researching, questioning, drafting, and revising planning artifacts @@ -33,6 +34,7 @@ When Flow planning is active: When Flow implementation is active: +- load `flow-execution` after the `flow` router skill so the monolithic Flow skill does not carry implementation-only detail into unrelated requests - read `.agents/workflow.md` and prefer the repo's canonical commands for setup, lint, test, typecheck, and full verification - preserve context for subagents with `spec.md`, parent PRD context, `patterns.md`, relevant `knowledge/` chapters, `learnings.md`, affected files, and verification requirements - prefer refined tasks before dispatching lighter-weight agents diff --git a/commands/flow-archive.md b/commands/flow-archive.md index a712bf7..9f42a6c 100644 --- a/commands/flow-archive.md +++ b/commands/flow-archive.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch # Flow Archive +> Lifecycle skill: use `flow-completion` through the `flow` router. + Archiving flow: **$ARGUMENTS** ## Phase 1: Validation diff --git a/commands/flow-docs.md b/commands/flow-docs.md index 7a17cd6..ea548f8 100644 --- a/commands/flow-docs.md +++ b/commands/flow-docs.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash # Flow Docs +> Lifecycle skill: use `flow-completion` through the `flow` router. + Managing documentation for Flow project. ## Phase 0: Setup Check diff --git a/commands/flow-finish.md b/commands/flow-finish.md index f9a8403..bf8d201 100644 --- a/commands/flow-finish.md +++ b/commands/flow-finish.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent # Flow Finish +> Lifecycle skill: use `flow-completion` through the `flow` router. + Completing flow: **$ARGUMENTS** ## The Closer Mandate diff --git a/commands/flow-implement.md b/commands/flow-implement.md index 0344231..bf7478a 100644 --- a/commands/flow-implement.md +++ b/commands/flow-implement.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, WebSearch # Flow Implement +> Lifecycle skill: use `flow-execution` through the `flow` router. + Implementing flow: **$ARGUMENTS** ## The Executor Mandate diff --git a/commands/flow-plan.md b/commands/flow-plan.md index f156771..b96db9a 100644 --- a/commands/flow-plan.md +++ b/commands/flow-plan.md @@ -5,6 +5,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion # Flow Plan +> Lifecycle skill: use `flow-planning` through the `flow` router. + ## The Planner Mandate **CRITICAL:** `/flow:plan` is the entry point for single flows. Its primary role is to define the roadmap by creating **Beads Tasks** (source of truth) and syncing them to a human-readable `spec.md`. diff --git a/commands/flow-prd.md b/commands/flow-prd.md index 5b69bc9..d039ec6 100644 --- a/commands/flow-prd.md +++ b/commands/flow-prd.md @@ -5,6 +5,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion # Flow PRD +> Lifecycle skill: use `flow-planning` through the `flow` router. + ## The Orchestrator Mandate **CRITICAL:** `/flow:prd` is the entry point for large features. Its primary role is to initialize the **Beads Epic** (source of truth) and define the high-level roadmap. diff --git a/commands/flow-refine.md b/commands/flow-refine.md index eb82bad..caf8e52 100644 --- a/commands/flow-refine.md +++ b/commands/flow-refine.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch # Flow Refine +> Lifecycle skill: use `flow-planning` through the `flow` router. + Refining flow: **$ARGUMENTS** ## The Refiner Mandate diff --git a/commands/flow-refresh.md b/commands/flow-refresh.md index 1b1d5bd..762b856 100644 --- a/commands/flow-refresh.md +++ b/commands/flow-refresh.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash # Flow Refresh +> Lifecycle skill: use `flow-sync-status` through the `flow` router. + Refreshing context for codebase drift: **$ARGUMENTS** ## Phase 1: Load Current Context diff --git a/commands/flow-research.md b/commands/flow-research.md index 2ff7d91..e13a648 100644 --- a/commands/flow-research.md +++ b/commands/flow-research.md @@ -6,6 +6,8 @@ allowed-tools: Read, Glob, Grep, Bash, WebSearch # Flow Research +> Lifecycle skill: use `flow-planning` through the `flow` router. + Conducting research for: **$ARGUMENTS** ## Phase 0: Setup Check diff --git a/commands/flow-revert.md b/commands/flow-revert.md index 41aba89..9d32764 100644 --- a/commands/flow-revert.md +++ b/commands/flow-revert.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Bash # Flow Revert +> Lifecycle skill: use `flow-completion` through the `flow` router. + Reverting: **$ARGUMENTS** ## Phase 1: Parse Target diff --git a/commands/flow-review.md b/commands/flow-review.md index c63140f..fed114c 100644 --- a/commands/flow-review.md +++ b/commands/flow-review.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent # Flow Review +> Lifecycle skill: use `flow-completion` through the `flow` router. + Reviewing flow: **$ARGUMENTS** ## 1.0 SYSTEM DIRECTIVE diff --git a/commands/flow-revise.md b/commands/flow-revise.md index 5c7020a..a47cc78 100644 --- a/commands/flow-revise.md +++ b/commands/flow-revise.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion # Flow Revise +> Lifecycle skill: use `flow-planning` through the `flow` router. + Revising flow: **$ARGUMENTS** ## Phase 1: Load Current State diff --git a/commands/flow-setup.md b/commands/flow-setup.md index f65c809..47d781e 100644 --- a/commands/flow-setup.md +++ b/commands/flow-setup.md @@ -5,6 +5,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__sequen # Flow Setup +> Lifecycle skill: use `flow-setup` through the `flow` router. + Initialize a project for context-driven development with Beads integration. > **Host boundary:** This command runs under Claude Code. Only Claude-owned files are created (e.g., `CLAUDE.md`). Do not write `.gemini/*`, `.geminiignore`, `.codex/*`, `.cursor/*`, or `.opencode/*` — each host's setup command owns its own configuration surface. diff --git a/commands/flow-status.md b/commands/flow-status.md index 493324f..14fabe4 100644 --- a/commands/flow-status.md +++ b/commands/flow-status.md @@ -5,6 +5,8 @@ allowed-tools: Read, Glob, Grep, Bash # Flow Status +> Lifecycle skill: use `flow-sync-status` through the `flow` router. + Display progress overview for all active flows. ## The Dashboard Mandate diff --git a/commands/flow-sync.md b/commands/flow-sync.md index 6013f68..f32f563 100644 --- a/commands/flow-sync.md +++ b/commands/flow-sync.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash # Flow Sync +> Lifecycle skill: use `flow-sync-status` through the `flow` router. + Syncing active backend state to disk for flow: **$ARGUMENTS** ## The Bridge Mandate diff --git a/commands/flow-task.md b/commands/flow-task.md index 9945c7e..a770fa2 100644 --- a/commands/flow-task.md +++ b/commands/flow-task.md @@ -6,6 +6,8 @@ allowed-tools: Read, Write, Bash # Flow Task +> Lifecycle skill: use `flow-planning` through the `flow` router. + Creating ephemeral exploration flow: **$ARGUMENTS** ## Overview diff --git a/commands/flow-validate.md b/commands/flow-validate.md index 0e44984..da1c9c2 100644 --- a/commands/flow-validate.md +++ b/commands/flow-validate.md @@ -5,6 +5,8 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash # Flow Validate +> Lifecycle skill: use `flow-setup` through the `flow` router. + Validate Flow project integrity and optionally fix issues. ## Phase 1: Directory Structure diff --git a/commands/flow/archive.toml b/commands/flow/archive.toml index 13634f9..e20534b 100644 --- a/commands/flow/archive.toml +++ b/commands/flow/archive.toml @@ -1,5 +1,8 @@ description = "Archive completed flows + elevate patterns" prompt = """ +## Lifecycle Skill +Use the `flow-completion` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI agent assistant for the Flow spec-driven development framework. Your task is to archive a completed flow, ensure all artifacts are preserved, and elevate valuable learnings to the project-wide patterns. diff --git a/commands/flow/cleanup.toml b/commands/flow/cleanup.toml index 84b58e3..202d619 100644 --- a/commands/flow/cleanup.toml +++ b/commands/flow/cleanup.toml @@ -1,5 +1,8 @@ description = "Groundskeeper: Global maintenance and optimization of .agents/" prompt = """ +## Lifecycle Skill +Use the `flow-sync-status` lifecycle skill through the `flow` router before carrying out this command. + # Flow Cleanup Global maintenance and optimization of the `.agents/` directory. diff --git a/commands/flow/docs.toml b/commands/flow/docs.toml index cfd9cef..a86bfcf 100644 --- a/commands/flow/docs.toml +++ b/commands/flow/docs.toml @@ -1,5 +1,8 @@ description = "Five-phase documentation workflow" prompt = """ +## Lifecycle Skill +Use the `flow-completion` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI documentation agent for the Flow spec-driven development framework. Your task is to manage comprehensive documentation through a five-phase workflow that ensures quality, captures institutional knowledge, and maintains a clean workspace. diff --git a/commands/flow/finish.toml b/commands/flow/finish.toml index 45c4cae..a29d939 100644 --- a/commands/flow/finish.toml +++ b/commands/flow/finish.toml @@ -1,5 +1,8 @@ description = "Complete flow work - verify, review, merge/PR/keep/discard" prompt = """ +## Lifecycle Skill +Use the `flow-completion` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are completing a Flow's development work. Your task is to verify all tests pass, finalize the Beads state, and help the user integrate their work. diff --git a/commands/flow/implement.toml b/commands/flow/implement.toml index 432fac3..2280523 100644 --- a/commands/flow/implement.toml +++ b/commands/flow/implement.toml @@ -1,5 +1,8 @@ description = "Execute tasks from plan (context-aware)" prompt = """ +## Lifecycle Skill +Use the `flow-execution` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are a delegator for the Flow framework. Your task is to transition the current request to the high-reasoning "Executor" subagent to ensure proper model routing and TDD discipline. diff --git a/commands/flow/plan.toml b/commands/flow/plan.toml index e5b27f3..96d66f1 100644 --- a/commands/flow/plan.toml +++ b/commands/flow/plan.toml @@ -1,5 +1,8 @@ description = "Create unified spec.md for a single Flow" prompt = """ +## Lifecycle Skill +Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are a delegator for the Flow framework. Your task is to transition the current request to the high-reasoning "Planner" subagent to ensure proper model routing and Zero-Ambiguity worksheet generation. diff --git a/commands/flow/prd.toml b/commands/flow/prd.toml index ca56db0..654f539 100644 --- a/commands/flow/prd.toml +++ b/commands/flow/prd.toml @@ -1,5 +1,8 @@ description = "Analyze goals and generate Master Roadmap (Sagas)" prompt = """ +## Lifecycle Skill +Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are a delegator for the Flow framework. Your task is to transition the current request to the high-reasoning "Orchestrator" subagent to ensure proper model routing and Zero-Ambiguity planning. diff --git a/commands/flow/refine.toml b/commands/flow/refine.toml index 2797d33..3d8d1ee 100644 --- a/commands/flow/refine.toml +++ b/commands/flow/refine.toml @@ -1,5 +1,8 @@ description = "Refine coarse tasks into implementation-ready plans" prompt = """ +## Lifecycle Skill +Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are the **Flow Refiner**. Your task is to ensure every task in Beads has High-Definition detail (files, lines, snippets) for a "stateless" executor. diff --git a/commands/flow/refresh.toml b/commands/flow/refresh.toml index fe7a2b4..c2a7f8f 100644 --- a/commands/flow/refresh.toml +++ b/commands/flow/refresh.toml @@ -1,5 +1,8 @@ description = "Sync context with codebase after external changes" prompt = """ +## Lifecycle Skill +Use the `flow-sync-status` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI agent assistant for the Flow spec-driven development framework. Your task is to refresh the flow's context files by re-scanning the codebase and updating `.agents/` metadata to reflect the current state. diff --git a/commands/flow/research.toml b/commands/flow/research.toml index ad63e2a..e889113 100644 --- a/commands/flow/research.toml +++ b/commands/flow/research.toml @@ -1,5 +1,8 @@ description = "Conduct pre-PRD research" prompt = """ +## Lifecycle Skill +Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI research agent for the Flow spec-driven development framework. Your task is to conduct thorough research BEFORE creating a PRD, gathering context that will inform better specifications and implementation plans. diff --git a/commands/flow/revert.toml b/commands/flow/revert.toml index 0ff6d87..1022283 100644 --- a/commands/flow/revert.toml +++ b/commands/flow/revert.toml @@ -1,5 +1,8 @@ description = "Git-aware revert of flows, phases, or tasks" prompt = """ +## Lifecycle Skill +Use the `flow-completion` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are a **Git-aware revert assistant** for the Flow framework with Beads integration. diff --git a/commands/flow/review.toml b/commands/flow/review.toml index 56e571b..2fb968f 100644 --- a/commands/flow/review.toml +++ b/commands/flow/review.toml @@ -1,5 +1,8 @@ description = "Dispatch code review with Beads-aware git range" prompt = """ +## Lifecycle Skill +Use the `flow-completion` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are dispatching a code review for a Flow's implementation. Your task is to determine the correct git range from Beads, dispatch a review subagent, and present actionable results. diff --git a/commands/flow/revise.toml b/commands/flow/revise.toml index 719593c..cfb46a3 100644 --- a/commands/flow/revise.toml +++ b/commands/flow/revise.toml @@ -1,5 +1,8 @@ description = "Update spec/plan when implementation reveals issues" prompt = """ +## Lifecycle Skill +Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command. + ## SYSTEM DIRECTIVE You are revising a flow's spec or plan because implementation has revealed new information. All revisions must be documented. diff --git a/commands/flow/setup.toml b/commands/flow/setup.toml index 295f74e..9c35291 100644 --- a/commands/flow/setup.toml +++ b/commands/flow/setup.toml @@ -1,5 +1,8 @@ description = "Initialize project with context files, Beads, and first flow" prompt = """ +## Lifecycle Skill +Use the `flow-setup` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI agent. Your primary function is to set up and manage a software project using the Flow methodology with Beads task persistence. This document is your operational protocol. Adhere to these instructions precisely and sequentially. Do not make assumptions. diff --git a/commands/flow/status.toml b/commands/flow/status.toml index 44a78da..05b38b2 100644 --- a/commands/flow/status.toml +++ b/commands/flow/status.toml @@ -1,5 +1,8 @@ description = "Display progress overview with Beads status" prompt = """ +## Lifecycle Skill +Use the `flow-sync-status` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI agent assistant for the Flow spec-driven development framework. Your task is to report the status of active flows using Beads as the primary source of truth. diff --git a/commands/flow/sync.toml b/commands/flow/sync.toml index 71d2df7..33fbd7a 100644 --- a/commands/flow/sync.toml +++ b/commands/flow/sync.toml @@ -1,5 +1,8 @@ description = "Synchronize context docs, Beads state, and export summaries" prompt = """ +## Lifecycle Skill +Use the `flow-sync-status` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI agent assistant for the Flow spec-driven development framework. Your task is to synchronize the current active backend task state back to the on-disk `spec.md` for a flow, refresh context documents based on the codebase, and optionally generate an export summary. diff --git a/commands/flow/task.toml b/commands/flow/task.toml index 50c7e75..ac045b5 100644 --- a/commands/flow/task.toml +++ b/commands/flow/task.toml @@ -1,5 +1,8 @@ description = "Create ephemeral task (no audit trail)" prompt = """ +## Lifecycle Skill +Use the `flow-planning` lifecycle skill through the `flow` router before carrying out this command. + ## 1.0 SYSTEM DIRECTIVE You are an AI agent assistant for the Flow framework. Your goal is to create a "Task" - a lightweight, ephemeral track for quick tasks, explorations, or experiments that don't need a full PRD. diff --git a/commands/flow/validate.toml b/commands/flow/validate.toml index ba65a44..365bc31 100644 --- a/commands/flow/validate.toml +++ b/commands/flow/validate.toml @@ -1,5 +1,8 @@ description = "Validate project integrity and fix issues" prompt = """ +## Lifecycle Skill +Use the `flow-setup` lifecycle skill through the `flow` router before carrying out this command. + ## SYSTEM DIRECTIVE You are validating a Flow project's integrity. Check all files, Beads status, and flow consistency. diff --git a/skills/alloydb-omni/SKILL.md b/skills/alloydb-omni/SKILL.md index 69c57d0..263d89f 100644 --- a/skills/alloydb-omni/SKILL.md +++ b/skills/alloydb-omni/SKILL.md @@ -1,6 +1,6 @@ --- name: alloydb-omni -description: "Auto-activate for alloydb-omni in compose/k8s configs. AlloyDB Omni expertise: run AlloyDB anywhere (local, on-prem, other clouds) with container-based deployment. Produces container-based AlloyDB Omni deployments for local dev and non-GCP environments. Use when: running AlloyDB locally for development, deploying Omni containers, configuring Kubernetes operators, or testing AlloyDB features without GCP. Not for GCP-managed AlloyDB (see alloydb) or vanilla PostgreSQL." +description: "Use when running AlloyDB Omni locally or outside GCP, configuring container deployments, Kubernetes operators, RPM installs, columnar engine tests, or local development that needs AlloyDB behavior." --- # AlloyDB Omni diff --git a/skills/alloydb-omni/agents/openai.yaml b/skills/alloydb-omni/agents/openai.yaml new file mode 100644 index 0000000..68797c8 --- /dev/null +++ b/skills/alloydb-omni/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "AlloyDB Omni" + short_description: "Containerized AlloyDB Omni setup, operators, RPMs, and local database workflows" diff --git a/skills/alloydb/SKILL.md b/skills/alloydb/SKILL.md index eb49abe..931a16f 100644 --- a/skills/alloydb/SKILL.md +++ b/skills/alloydb/SKILL.md @@ -1,6 +1,6 @@ --- name: alloydb -description: "Auto-activate for AlloyDB in GCP configs or docs. Google AlloyDB expertise: PostgreSQL-compatible managed database on GCP. Produces AlloyDB cluster configurations, connection patterns, and columnar engine setups on GCP. Use when: provisioning AlloyDB clusters, configuring read pools, using columnar engine, Private Service Access networking, or migrating from Cloud SQL. Not for AlloyDB Omni (see alloydb-omni) or vanilla PostgreSQL without AlloyDB features." +description: "Use when provisioning Google AlloyDB, configuring clusters or read pools, enabling columnar engine, setting up Private Service Access, tuning managed PostgreSQL on GCP, or migrating from Cloud SQL to AlloyDB." --- # AlloyDB diff --git a/skills/alloydb/agents/openai.yaml b/skills/alloydb/agents/openai.yaml new file mode 100644 index 0000000..fc7c826 --- /dev/null +++ b/skills/alloydb/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "AlloyDB" + short_description: "Google AlloyDB clusters, read pools, migrations, and managed PostgreSQL patterns" diff --git a/skills/angular/SKILL.md b/skills/angular/SKILL.md index 159ff3d..2655c73 100644 --- a/skills/angular/SKILL.md +++ b/skills/angular/SKILL.md @@ -1,6 +1,6 @@ --- name: angular -description: "Auto-activate for angular.json, *.component.ts, @Component decorator. Expert knowledge for modern Angular with signals, standalone components, control flow blocks, and current migration guidance. Use when building Angular apps with contemporary patterns and when validating version-specific API stability. Not for React (see react), Vue (see vue), or AngularJS (v1)." +description: "Use when editing Angular projects, angular.json, *.component.ts files, @Component code, signals, standalone components, control-flow blocks, Angular migrations, or Angular version-specific APIs." --- # Angular Framework Skill diff --git a/skills/angular/agents/openai.yaml b/skills/angular/agents/openai.yaml new file mode 100644 index 0000000..00b3be3 --- /dev/null +++ b/skills/angular/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Angular" + short_description: "Modern Angular components, signals, standalone APIs, and migration guidance" diff --git a/skills/apilookup/SKILL.md b/skills/apilookup/SKILL.md index e9f6f4d..69d64e5 100644 --- a/skills/apilookup/SKILL.md +++ b/skills/apilookup/SKILL.md @@ -1,6 +1,6 @@ --- name: apilookup -description: "Use when any task depends on external API/framework behavior, SDK references, library versions, breaking changes, migration guides, changelogs, or release notes. Auto-activate for uncertainty about third-party docs, version compatibility, deprecations, or current syntax before implementation decisions. Produces version-verified documentation references with links to official sources, staleness warnings, and version gap notes." +description: "Use when work depends on current external API behavior, SDK docs, framework versions, breaking changes, migration guides, changelogs, release notes, deprecations, or syntax that may have changed." --- # API Lookup Skill diff --git a/skills/apilookup/agents/openai.yaml b/skills/apilookup/agents/openai.yaml new file mode 100644 index 0000000..fd579f3 --- /dev/null +++ b/skills/apilookup/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "API Lookup" + short_description: "Version-verified external API, SDK, framework, and changelog lookup workflow" diff --git a/skills/architecture-critic/SKILL.md b/skills/architecture-critic/SKILL.md index d791c73..a914c38 100644 --- a/skills/architecture-critic/SKILL.md +++ b/skills/architecture-critic/SKILL.md @@ -1,6 +1,6 @@ --- name: architecture-critic -description: "Auto-activate when evaluating system architecture, reviewing component boundaries, assessing coupling between modules, planning large refactors, introducing new layers or abstractions, or when design decisions have long-term structural consequences. Produces structural assessment with boundary evaluation, coupling analysis, and time-horizon risk — what will be painful to change in 6-12 months. Use when: architecture review needed, evaluating maintainability of a design, checking for premature abstraction or missing abstraction, or assessing whether component boundaries are in the right place. Not for code style, naming conventions, or implementation details within well-bounded components." +description: "Use when evaluating architecture, component boundaries, coupling, cohesion, abstractions, large refactors, new layers, maintainability risks, or design choices with long-term structural consequences." --- # Architecture Critic diff --git a/skills/architecture-critic/agents/openai.yaml b/skills/architecture-critic/agents/openai.yaml new file mode 100644 index 0000000..9d352d6 --- /dev/null +++ b/skills/architecture-critic/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Architecture Critic" + short_description: "Structural review for boundaries, coupling, abstractions, and long-term maintainability" diff --git a/skills/bash/SKILL.md b/skills/bash/SKILL.md index 16865ab..9441e6d 100644 --- a/skills/bash/SKILL.md +++ b/skills/bash/SKILL.md @@ -1,6 +1,6 @@ --- name: bash -description: "Auto-activate for .sh files, #!/bin/bash, #!/usr/bin/env bash. Bash scripting expertise following Google Shell Style Guide. Produces shell scripts following Google Shell Style Guide with proper error handling, quoting, and safety patterns. Use when: writing shell scripts, automating tasks, processing text, or creating CLI tools. Covers error handling, variable quoting, function patterns, and portable scripting. Not for Python/Ruby scripts that happen to call shell commands." +description: "Use when editing shell scripts, .sh files, bash shebangs, CLI automation, text processing pipelines, shell error handling, quoting, traps, functions, or portable Bash patterns." --- # Bash Scripting diff --git a/skills/bash/agents/openai.yaml b/skills/bash/agents/openai.yaml new file mode 100644 index 0000000..5339d94 --- /dev/null +++ b/skills/bash/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Bash" + short_description: "Shell scripting with quoting, safety, error handling, and Google style patterns" diff --git a/skills/biome/SKILL.md b/skills/biome/SKILL.md index 35595bd..8335814 100644 --- a/skills/biome/SKILL.md +++ b/skills/biome/SKILL.md @@ -1,6 +1,6 @@ --- name: biome -description: "Auto-activate for biome.json, biome.jsonc. Expert knowledge for Biome toolchain (Linter, Formatter). Use when configuring workspace styles, troubleshooting linter errors, or setting up ignores/overrides for frontend projects. Produces Biome linter/formatter configurations with workspace overrides. Not for ESLint, Prettier, or non-JS/TS toolchains." +description: "Use when editing biome.json or biome.jsonc, configuring Biome linting or formatting, troubleshooting Biome diagnostics, setting ignores or overrides, or replacing ESLint/Prettier in JS and TS projects." --- # Biome Skill diff --git a/skills/biome/agents/openai.yaml b/skills/biome/agents/openai.yaml new file mode 100644 index 0000000..14f445c --- /dev/null +++ b/skills/biome/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Biome" + short_description: "Biome lint, format, workspace config, ignores, and overrides" diff --git a/skills/bun/SKILL.md b/skills/bun/SKILL.md index fcde3d3..5c83e4c 100644 --- a/skills/bun/SKILL.md +++ b/skills/bun/SKILL.md @@ -1,6 +1,6 @@ --- name: bun -description: "Auto-activate for bun.lockb, bunfig.toml. Usage of Bun as a high-performance JavaScript runtime, bundler, and test runner. Use when: running JS/TS code with Bun, using bun install, configuring Bun workspaces, or fixing low-latency node runtimes. Not for Node.js-specific APIs that Bun doesn't support, or Deno." +description: "Use when using bun.lockb, bunfig.toml, bun install, Bun workspaces, Bun test, Bun runtime APIs, JS or TS scripts run with Bun, bundling, or Node compatibility checks for Bun." --- # Bun Skill diff --git a/skills/bun/agents/openai.yaml b/skills/bun/agents/openai.yaml new file mode 100644 index 0000000..c2af5fb --- /dev/null +++ b/skills/bun/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Bun" + short_description: "Bun runtime, package manager, workspaces, tests, and bundling patterns" diff --git a/skills/challenge/SKILL.md b/skills/challenge/SKILL.md index 5fa580f..f3b6848 100644 --- a/skills/challenge/SKILL.md +++ b/skills/challenge/SKILL.md @@ -1,6 +1,6 @@ --- name: challenge -description: "Auto-activate when critically questioning claims, pushing back on assumptions, disagreeing with an approach, sanity-checking contentious decisions, or when a response feels like reflexive agreement. Produces an honest assessment — confirms what holds up with evidence, identifies specific flaws, and delivers a direct verdict without hedging. Use when: validating claims, stress-testing ideas, preventing sycophantic agreement, questioning confident assertions, or saying 'are you sure about that?' Not for generating agreement, validating feelings, or confirming what the user wants to hear." +description: "Use when questioning claims, pushing back on assumptions, sanity-checking decisions, evaluating confident assertions, avoiding reflexive agreement, or answering prompts like \"are you sure?\"" --- # Challenge diff --git a/skills/challenge/agents/openai.yaml b/skills/challenge/agents/openai.yaml new file mode 100644 index 0000000..9b4f1ea --- /dev/null +++ b/skills/challenge/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Challenge" + short_description: "Critical reassessment for assumptions, claims, agreement, and weak conclusions" diff --git a/skills/cloud-run/SKILL.md b/skills/cloud-run/SKILL.md index a8e1258..e1dab2c 100644 --- a/skills/cloud-run/SKILL.md +++ b/skills/cloud-run/SKILL.md @@ -1,6 +1,6 @@ --- name: cloud-run -description: "Auto-activate for Cloud Run service.yaml, gcloud run commands. Google Cloud Run serverless platform: Dockerfile, containerized services, Cloud Run Jobs, cold starts, traffic splitting. Produces Cloud Run service configurations, Dockerfiles, and deployment workflows for containerized serverless apps on GCP. Use when: deploying containers to Cloud Run, writing Dockerfiles for serverless, or tuning scaling/concurrency. Not for GKE (see gke), Cloud Functions, or non-containerized deployments." +description: "Use when deploying containers to Google Cloud Run, editing service.yaml, using gcloud run, configuring Cloud Run Jobs, scaling, concurrency, traffic splitting, cold starts, networking, or serverless Dockerfiles." --- # Google Cloud Run Skill diff --git a/skills/cloud-run/agents/openai.yaml b/skills/cloud-run/agents/openai.yaml new file mode 100644 index 0000000..61ae291 --- /dev/null +++ b/skills/cloud-run/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Cloud Run" + short_description: "Google Cloud Run services, jobs, scaling, containers, networking, and deployments" diff --git a/skills/cloud-sql/SKILL.md b/skills/cloud-sql/SKILL.md index f779650..10c783a 100644 --- a/skills/cloud-sql/SKILL.md +++ b/skills/cloud-sql/SKILL.md @@ -1,6 +1,6 @@ --- name: cloud-sql -description: "Auto-activate for Cloud SQL gcloud commands, cloud-sql-proxy usage, or Cloud SQL connection strings. Google Cloud SQL expertise: fully managed PostgreSQL, MySQL, and SQL Server on GCP. Produces Cloud SQL instance configurations, connection patterns, backup strategies, and replication setups. Use when: provisioning Cloud SQL instances, configuring Auth Proxy connections, setting up read replicas, managing backups and PITR, or migrating to Cloud SQL. For higher performance PostgreSQL workloads see flow:alloydb. For GKE deployment patterns see flow:gke." +description: "Use when provisioning Google Cloud SQL, configuring Cloud SQL Auth Proxy, connection strings, read replicas, backups, PITR, private IP, database migrations, or managed PostgreSQL/MySQL/SQL Server on GCP." --- # Cloud SQL diff --git a/skills/cloud-sql/agents/openai.yaml b/skills/cloud-sql/agents/openai.yaml new file mode 100644 index 0000000..059e2ae --- /dev/null +++ b/skills/cloud-sql/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Cloud SQL" + short_description: "Google Cloud SQL instances, Auth Proxy, replicas, backups, and migrations" diff --git a/skills/consensus/SKILL.md b/skills/consensus/SKILL.md index 9d4193d..3d95488 100644 --- a/skills/consensus/SKILL.md +++ b/skills/consensus/SKILL.md @@ -1,6 +1,6 @@ --- name: consensus -description: "Auto-activate when evaluating architectural decisions, comparing technology choices, weighing design trade-offs, assessing feature proposals, making build-vs-buy decisions, choosing between competing approaches, when a decision has significant long-term consequences, when multiple teams are affected, or when the cost of reversal is high. Produces a structured recommendation with confidence level (low/medium/high), pro/con analysis, risk assessment, and concrete next steps. Use when: decisions need structured multi-perspective analysis, risk assessment from multiple angles, decisions impact more than one team, decisions span more than a few months, or when the stakes are high enough to warrant deliberate evaluation. Not for routine code review, simple config choices, or styling preferences." +description: "Use when comparing architectural choices, technology options, build-vs-buy decisions, feature proposals, high-impact tradeoffs, multi-team decisions, hard-to-reverse choices, or risk-heavy alternatives." --- # Consensus diff --git a/skills/consensus/agents/openai.yaml b/skills/consensus/agents/openai.yaml new file mode 100644 index 0000000..349304d --- /dev/null +++ b/skills/consensus/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Consensus" + short_description: "Structured decision analysis for tradeoffs, risks, and competing approaches" diff --git a/skills/cpp/SKILL.md b/skills/cpp/SKILL.md index 7cea41d..b60f20a 100644 --- a/skills/cpp/SKILL.md +++ b/skills/cpp/SKILL.md @@ -1,6 +1,6 @@ --- name: cpp -description: "Auto-activate for .cpp, .hpp, .cc, .hh, .cxx, CMakeLists.txt. Modern C++ development patterns for extensions and backend systems. Produces modern C++ code with proper build systems, resource management, and CI/CD integration. Use when: designing C++ code, setting up CI/CD pipelines, managing builds, or working with resource ownership, APIs, error handling, and concurrency in C++ projects. Not for C code or legacy C++ without modern idioms." +description: "Use when editing C++ files, .cpp, .hpp, .cc, .hh, .cxx, CMakeLists.txt, modern C++ APIs, resource ownership, error handling, concurrency, build systems, or native extension code." --- # C++ Development diff --git a/skills/cpp/agents/openai.yaml b/skills/cpp/agents/openai.yaml index 78c3240..c60fd97 100644 --- a/skills/cpp/agents/openai.yaml +++ b/skills/cpp/agents/openai.yaml @@ -1,3 +1,3 @@ interface: display_name: "C++ Development" - short_description: "Modern C++ design, build, and CI workflow" + short_description: "Modern C++ design, build systems, ownership, APIs, concurrency, and CI" diff --git a/skills/deepthink/SKILL.md b/skills/deepthink/SKILL.md index 9499e28..2b2fcb3 100644 --- a/skills/deepthink/SKILL.md +++ b/skills/deepthink/SKILL.md @@ -1,6 +1,6 @@ --- name: deepthink -description: "Auto-activate when a problem resists quick answers, when initial analysis feels shallow, when debugging hits a wall, when architectural reasoning needs depth, when confidence in a conclusion is low, when analysis feels like it is going in circles, or when the first answer feels too easy for a hard problem. Produces a confidence-tracked investigation with explicit hypothesis evolution, evidence log, and a specific actionable conclusion. Use when: complex reasoning needed, hypothesis testing required, going in circles on a problem, need to track what has been explored vs what remains, analysis feels shallow, confidence is low, or when debugging hits a wall. Not for clear questions with obvious answers, simple lookups, or problems that yield to direct investigation." +description: "Use when a problem resists quick answers, debugging stalls, analysis feels shallow, confidence is low, hypotheses are competing, reasoning loops repeat, or a hard problem needs evidence tracking." --- # Deepthink diff --git a/skills/deepthink/agents/openai.yaml b/skills/deepthink/agents/openai.yaml new file mode 100644 index 0000000..94337ea --- /dev/null +++ b/skills/deepthink/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Deepthink" + short_description: "Hypothesis-driven investigation for hard debugging and uncertain reasoning" diff --git a/skills/devils-advocate/SKILL.md b/skills/devils-advocate/SKILL.md index 483395a..3eb7e3f 100644 --- a/skills/devils-advocate/SKILL.md +++ b/skills/devils-advocate/SKILL.md @@ -1,6 +1,6 @@ --- name: devils-advocate -description: "Auto-activate when reviewing PRs, evaluating design proposals, assessing technical plans, or when a decision is being made without visible pushback. Produces a prioritized list of risks, unverified assumptions, and overlooked failure modes — each with severity, explanation, and recommended action. Use when: code review needs adversarial perspective, a design feels too consensus-driven, assumptions need stress-testing, or when everyone agrees too quickly on an approach. Not for rubber-stamping, routine style review, or agreeing with the user's direction." +description: "Use when reviewing PRs, evaluating design proposals, assessing technical plans, stress-testing assumptions, looking for overlooked failure modes, or adding pushback before a decision." --- # Devil's Advocate diff --git a/skills/devils-advocate/agents/openai.yaml b/skills/devils-advocate/agents/openai.yaml new file mode 100644 index 0000000..56a2604 --- /dev/null +++ b/skills/devils-advocate/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Devil's Advocate" + short_description: "Adversarial review for plans, PRs, assumptions, and overlooked failure modes" diff --git a/skills/dishka/SKILL.md b/skills/dishka/SKILL.md index 94eebf6..2a19d24 100644 --- a/skills/dishka/SKILL.md +++ b/skills/dishka/SKILL.md @@ -1,6 +1,6 @@ --- name: dishka -description: "Auto-activate for dishka imports. Dishka dependency injection framework: Provider, Scope, Container, FromDishka, Inject. Use when: setting up DI containers, defining providers/scopes, or integrating dependency injection with Litestar or FastAPI. Produces Dishka DI container configurations with providers, scopes, and framework integrations. Not for manual dependency injection or other DI frameworks." +description: "Use when editing Dishka dependency injection code, Provider, Scope, Container, FromDishka, Inject, DI scopes, providers, testing containers, or Litestar/FastAPI Dishka integrations." --- # Dishka Dependency Injection Skill diff --git a/skills/dishka/agents/openai.yaml b/skills/dishka/agents/openai.yaml new file mode 100644 index 0000000..5a2e93a --- /dev/null +++ b/skills/dishka/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Dishka" + short_description: "Dishka dependency injection providers, scopes, containers, and integrations" diff --git a/skills/docgen/SKILL.md b/skills/docgen/SKILL.md index f37b606..48e661b 100644 --- a/skills/docgen/SKILL.md +++ b/skills/docgen/SKILL.md @@ -1,6 +1,6 @@ --- name: docgen -description: "Auto-activate when generating documentation, writing API docs, documenting modules or components, creating README content, building reference guides, or systematically documenting a codebase. Produces structured per-component documentation with completeness tracking — every file in scope gets documented, progress is explicit ([3/12 files]). Use when: documenting multiple files or components, ensuring complete coverage of a module, generating structured docs from code, or when /flow-docs needs systematic file-by-file analysis. Not for ad-hoc comments in code, inline docstrings, or single-function explanations." +description: "Use when generating documentation, writing API docs, documenting modules or components, creating README content, building reference guides, or documenting many files with explicit coverage tracking." --- # Docgen diff --git a/skills/docgen/agents/openai.yaml b/skills/docgen/agents/openai.yaml new file mode 100644 index 0000000..e238725 --- /dev/null +++ b/skills/docgen/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Documentation Generation" + short_description: "Systematic codebase, API, module, component, and reference documentation" diff --git a/skills/docker/SKILL.md b/skills/docker/SKILL.md index ec71c64..bad999e 100644 --- a/skills/docker/SKILL.md +++ b/skills/docker/SKILL.md @@ -1,6 +1,6 @@ --- name: docker -description: "Auto-activate for Dockerfile, docker-compose.yml, docker-compose.yaml, .dockerignore. Docker expertise: multi-stage builds, distroless images, Compose, BuildKit, and container optimization. Use when: writing Dockerfiles, optimizing image size, configuring docker-compose, using BuildKit features, or deploying containerized applications. Produces optimized Dockerfiles with multi-stage builds, Compose configurations, and BuildKit patterns. Not for Podman (see podman) or container orchestration (see gke/cloud-run)." +description: "Use when editing Dockerfile, Containerfile-like Docker syntax, docker-compose.yml, docker-compose.yaml, .dockerignore, multi-stage builds, BuildKit cache mounts, Compose services, or image optimization." --- # Docker diff --git a/skills/docker/agents/openai.yaml b/skills/docker/agents/openai.yaml new file mode 100644 index 0000000..ce7ee62 --- /dev/null +++ b/skills/docker/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Docker" + short_description: "Dockerfiles, Compose, BuildKit, image optimization, and container workflows" diff --git a/skills/duckdb/SKILL.md b/skills/duckdb/SKILL.md index dc148af..14a526e 100644 --- a/skills/duckdb/SKILL.md +++ b/skills/duckdb/SKILL.md @@ -1,6 +1,6 @@ --- name: duckdb -description: "Auto-activate for .duckdb files, duckdb imports. Comprehensive DuckDB expertise: advanced analytical SQL patterns, performance tuning, data engineering (ETL, multi-source reads, cloud storage), client APIs for Python/Node/Rust/Java/R/Go/WASM, extension development, function reference, and configuration/administration. Use when: writing DuckDB queries, optimizing performance, building data pipelines, connecting from any language, developing extensions, importing/exporting CSV/Parquet/JSON/Delta/Iceberg, or configuring DuckDB for production analytics workloads. Not for OLTP databases (see postgres/mysql) or traditional data warehouses." +description: "Use when writing DuckDB SQL, using .duckdb files, duckdb imports, analytical queries, CSV/Parquet/JSON ingestion, ETL pipelines, extensions, client APIs, configuration, or performance tuning." --- # DuckDB diff --git a/skills/duckdb/agents/openai.yaml b/skills/duckdb/agents/openai.yaml new file mode 100644 index 0000000..9fa5228 --- /dev/null +++ b/skills/duckdb/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "DuckDB" + short_description: "DuckDB SQL, analytics, ETL, extensions, clients, and performance tuning" diff --git a/skills/flow-completion/SKILL.md b/skills/flow-completion/SKILL.md new file mode 100644 index 0000000..4b3551e --- /dev/null +++ b/skills/flow-completion/SKILL.md @@ -0,0 +1,45 @@ +--- +name: flow-completion +description: "Use when reviewing, finishing, archiving, reverting, validating, or cleaning up Flow work after implementation or phase completion." +--- + +# Flow Completion + +Use this lifecycle skill for review, finish, archive, revert, docs, validation, and final cleanup work. + +## Workflow + +1. Run fresh verification before claiming a phase or flow is complete. +2. Review implementation against the spec, tests, patterns, security, architecture, and performance risks as appropriate. +3. Capture reusable learnings and elevate patterns into project knowledge. +4. Archive completed flows and preserve current-state guidance. +5. For reverts, identify the logical Flow scope and avoid unrelated user changes. + +## Guardrails + +- No completion claim without fresh verification evidence. +- Do not archive flows whose code, tests, Beads tasks, and markdown views disagree. +- Do not revert unrelated files or user changes. +- Keep knowledge chapters current-state oriented; avoid historical logs outside learnings. + +## Validation + +- Run full relevant test and validation commands before finish/archive. +- Confirm Beads tasks are closed or intentionally blocked/deferred. +- Confirm `spec.md`, learnings, patterns, and knowledge chapters reflect the current state. + +## References Index + +- [Review](../flow/references/review.md) +- [Finish](../flow/references/finish.md) +- [Archive](../flow/references/archive.md) +- [Revert](../flow/references/revert.md) +- [Docs](../flow/references/docs.md) +- [Validate](../flow/references/validate.md) +- [Cleanup](../flow/references/cleanup.md) + +## Example + +User: "Finish this flow." + +Action: run verification, review against the spec, close or explain remaining tasks, sync markdown, elevate reusable patterns, and present finish options. diff --git a/skills/flow-completion/agents/openai.yaml b/skills/flow-completion/agents/openai.yaml new file mode 100644 index 0000000..4dcdeea --- /dev/null +++ b/skills/flow-completion/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Flow Completion" + short_description: "Review, finish, archive, revert, validate, and clean up completed Flow work" diff --git a/skills/flow-execution/SKILL.md b/skills/flow-execution/SKILL.md new file mode 100644 index 0000000..15f44e2 --- /dev/null +++ b/skills/flow-execution/SKILL.md @@ -0,0 +1,40 @@ +--- +name: flow-execution +description: "Use when implementing Flow tasks from Beads or spec.md, claiming ready work, applying TDD, recording task notes, committing, and syncing after task state changes." +--- + +# Flow Execution + +Use this lifecycle skill when implementation starts after a Flow plan or ready Beads task exists. + +## Workflow + +1. Select ready work from `bd ready` and claim it before editing. +2. Read the relevant spec, notes, patterns, affected files, and validation commands. +3. Record investigation findings with `bd note`. +4. Follow red-green-refactor: write the failing test, verify the failure, implement minimally, verify green, then refactor. +5. Commit targeted changes, close the Beads task with evidence, and sync markdown when policy requires it. + +## Guardrails + +- Do not manually edit task status markers in markdown. +- Do not skip failing-test evidence for behavior changes. +- Do not silently descope messy tasks; refine or ask how to prioritize. +- Preserve unrelated user changes and keep edits scoped to the claimed task. + +## Validation + +- Verify the new test failed for the intended reason before implementation. +- Run focused tests after each task and the repo’s aggregate verification before phase completion. +- Record test output, commit reference, and closure reason in Beads. + +## References Index + +- [Implement](../flow/references/implement.md) +- [Discipline](../flow/references/discipline.md) + +## Example + +User: "Implement auth flow." + +Action: claim the next ready Beads task, add code-path notes, write a failing auth test, implement the minimal behavior, verify, commit, close the task, and sync. diff --git a/skills/flow-execution/agents/openai.yaml b/skills/flow-execution/agents/openai.yaml new file mode 100644 index 0000000..4d2b482 --- /dev/null +++ b/skills/flow-execution/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Flow Execution" + short_description: "Claim Beads tasks, implement with TDD, commit, close tasks, and sync" diff --git a/skills/flow-planning/SKILL.md b/skills/flow-planning/SKILL.md new file mode 100644 index 0000000..e680c71 --- /dev/null +++ b/skills/flow-planning/SKILL.md @@ -0,0 +1,44 @@ +--- +name: flow-planning +description: "Use when drafting PRDs, researching, planning, refining, revising, or creating .agents/specs//spec.md worksheets for Flow." +--- + +# Flow Planning + +Use this lifecycle skill for PRDs, research, single-flow planning, refinement, revisions, and task creation. + +## Workflow + +1. Read project context, patterns, knowledge chapters, and relevant existing specs before asking questions. +2. Research code paths and external APIs before locking implementation decisions. +3. Create PRDs as roadmap epics and single-flow specs as implementation worksheets. +4. Refine until tasks include concrete files, behavior, tests, commands, and acceptance criteria. +5. Create Beads epics/tasks and sync markdown views according to policy. + +## Guardrails + +- Planning must be decision-complete; do not defer obvious research to implementation. +- Ask only product or tradeoff questions that cannot be answered from the repo. +- Store plans under `.agents/specs//`, not ad hoc docs paths. +- Do not modify production code during planning. + +## Validation + +- Confirm every requirement maps to an implementation task and test scenario. +- Confirm tasks are small enough for a low-context executor to complete without guessing. +- Run spec review or code-reviewer validation before presenting final planning artifacts when available. + +## References Index + +- [PRD](../flow/references/prd.md) +- [Plan](../flow/references/plan.md) +- [Research](../flow/references/research.md) +- [Refine](../flow/references/refine.md) +- [Revise](../flow/references/revise.md) +- [Task](../flow/references/task.md) + +## Example + +User: "Plan skill trigger optimization." + +Action: inspect current skills and validators, ask unresolved product tradeoffs, create a Flow spec with Beads tasks, and refine until the implementation path is explicit. diff --git a/skills/flow-planning/agents/openai.yaml b/skills/flow-planning/agents/openai.yaml new file mode 100644 index 0000000..ffca508 --- /dev/null +++ b/skills/flow-planning/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Flow Planning" + short_description: "Draft PRDs, research, specs, refinement worksheets, and Beads task graphs" diff --git a/skills/flow-setup/SKILL.md b/skills/flow-setup/SKILL.md new file mode 100644 index 0000000..c01036c --- /dev/null +++ b/skills/flow-setup/SKILL.md @@ -0,0 +1,41 @@ +--- +name: flow-setup +description: "Use when initializing Flow in a repo, configuring .agents, installing or checking Beads bd, setting local-only sync policy, or creating first project context files." +--- + +# Flow Setup + +Use this lifecycle skill for project initialization, installation checks, setup validation, and first context files. + +## Workflow + +1. Detect project root, existing `.agents/` state, Beads availability, and repo-native commands. +2. If Beads is missing, offer official Beads (`bd`) installation or no-Beads degraded mode. +3. Initialize Flow context files from templates and prefer local-only Beads settings. +4. Store setup decisions in Beads notes when a backend exists. +5. Re-run setup validation before handing off to planning. + +## Guardrails + +- Prefer `.git/info/exclude` for local-only ignores. +- Do not edit `.gitignore` unless the user wants shared repository policy. +- Do not run `bd dolt push`, export, or auto-stage unless policy explicitly allows it. +- Keep setup idempotent; preserve existing user context files and merge rather than overwrite. + +## Validation + +- Confirm `.agents/` root, `workflow.md`, `patterns.md`, `knowledge/index.md`, and Beads config existence when setup is expected. +- Confirm Beads config defaults are local-only: no git ops, no auto export, and no auto git add. +- Run repository validation commands documented in `.agents/workflow.md` or hook context. + +## References Index + +- [Setup command details](../flow/references/setup.md) +- [Validate command details](../flow/references/validate.md) +- [Refresh command details](../flow/references/refresh.md) + +## Example + +User: "Use Flow to set up this repo." + +Action: detect the repo root, initialize `.agents/`, configure local-only Beads, capture setup notes, validate files, then hand off to `flow-planning` for the first flow. diff --git a/skills/flow-setup/agents/openai.yaml b/skills/flow-setup/agents/openai.yaml new file mode 100644 index 0000000..ec34a7c --- /dev/null +++ b/skills/flow-setup/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Flow Setup" + short_description: "Initialize Flow context, Beads, local-only policy, and setup validation" diff --git a/skills/flow-sync-status/SKILL.md b/skills/flow-sync-status/SKILL.md new file mode 100644 index 0000000..2e2dbff --- /dev/null +++ b/skills/flow-sync-status/SKILL.md @@ -0,0 +1,42 @@ +--- +name: flow-sync-status +description: "Use when syncing Beads state to markdown, checking Flow status, refreshing context docs, validating task markers, or reporting ready/blocked Flow work." +--- + +# Flow Sync And Status + +Use this lifecycle skill for status dashboards, sync, context refresh, cleanup checks, and drift reporting. + +## Workflow + +1. Read `.agents/beads.json` before any sync/export decision. +2. Pull Beads state and notes as the source of truth. +3. Regenerate synchronized markdown views without changing requirement text. +4. Detect drift in workflow commands, tech stack, patterns, knowledge chapters, and references. +5. Report ready, blocked, in-progress, and stale work with clear next actions. + +## Guardrails + +- Sync reads backend state; do not close, block, or mutate tasks during status reporting. +- Do not run export, auto-stage, or Dolt push unless policy or the user explicitly allows it. +- Preserve human-written spec content; only update synchronized task/status regions. +- Ask before applying context-doc updates when sync detects drift. + +## Validation + +- Confirm status comes from Beads, not markdown markers. +- Confirm broken file references, workflow drift, and sync policy decisions are reported. +- For this repo, run `make validate-skills` after skill or command sync changes. + +## References Index + +- [Sync](../flow/references/sync.md) +- [Status](../flow/references/status.md) +- [Refresh](../flow/references/refresh.md) +- [Cleanup](../flow/references/cleanup.md) + +## Example + +User: "Flow status." + +Action: read Beads state, summarize active flows, ready tasks, blockers, recent notes, and whether markdown views need sync. diff --git a/skills/flow-sync-status/agents/openai.yaml b/skills/flow-sync-status/agents/openai.yaml new file mode 100644 index 0000000..70e8d9c --- /dev/null +++ b/skills/flow-sync-status/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Flow Sync And Status" + short_description: "Sync Beads state, report status, refresh context, and detect drift" diff --git a/skills/flow/SKILL.md b/skills/flow/SKILL.md index 8b83eee..2a12987 100644 --- a/skills/flow/SKILL.md +++ b/skills/flow/SKILL.md @@ -1,333 +1,49 @@ --- name: flow -description: "Use when a project has `.agents/`, when the user asks to set up, plan, draft a PRD, research, refine tasks, implement, sync, review, finish, archive, or otherwise work through the Flow lifecycle. Applies to `/flow:*` intents, `.agents/specs/` edits, Beads backend work, and spec-first/TDD workflows that should automatically route into the matching Flow process." +description: "Use when a repository has .agents, when the user asks for Flow lifecycle routing, Beads-backed task memory, spec-first planning, TDD implementation, sync/status, review, finish, archive, or /flow:* help." --- -# Flow - Context-Driven Development +# Flow Router -Use the Flow skill for context-driven development workflows in repos that use `.agents/`. The environment (Beads backend, project root, and tooling) is **automatically detected via hooks** at the start of every session and provided in your ``. +Flow coordinates Context-Driven Development in `.agents/` repositories. Keep this skill small: use it to identify the active lifecycle phase, enforce the Beads-first invariants, and load the matching lifecycle skill. -## The Beads-First Mandate +## Workflow -**CRITICAL:** Beads (`bd`) is the **Primary Source of Truth** for task state and persistent context. Markdown files (`spec.md`, `prd.md`) are **Synchronized Views** of this state. +1. Check hook-provided Flow context first; otherwise detect `.agents/`, Beads (`bd`), git branch, and repo-native commands. +2. Route the request: + - Setup, validation, install, context initialization: use `flow-setup`. + - PRD, research, plan, refine, revise, task creation: use `flow-planning`. + - Implement, claim ready tasks, TDD, commit, task close: use `flow-execution`. + - Sync, status, refresh, cleanup, context drift: use `flow-sync-status`. + - Review, finish, archive, revert, docs, phase completion: use `flow-completion`. +3. Record durable discoveries and task state in Beads. Markdown files are synchronized views. +4. Prefer repo-native commands from `.agents/workflow.md` or hook context for validation. -- **PRDs are Epics**: `flow:prd` creates a Master Roadmap by initializing Beads **Epics**. -- **Plans are Task Graphs**: `flow:plan` defines the roadmap by creating Beads **Tasks** linked to the flow epic. -- **Context is Notes**: ALL design decisions, investigation findings, and implementation notes MUST be attached to work items using `bd note "..."`. This ensures context survives session resets and compaction. -- **Sync is Mandatory**: Run `/flow:sync` after any Beads mutation to update the human-readable Markdown view. +## Guardrails -## The Zero-Ambiguity Mandate +- Never edit task markers (`[ ]`, `[~]`, `[x]`, `[!]`, `[-]`) manually in `spec.md`. +- Do not run backend export, auto-stage, Dolt push, or git operations through Beads unless `.agents/beads.json` allows it or the user asks. +- Store Flow specs and planning artifacts under `.agents/specs//`. +- Make minimal targeted changes and record findings with `bd note "..."` when work exceeds a quick fix. -**CRITICAL:** Every specification (`spec.md`) MUST be a "High-Definition" document. It is NOT a summary; it is a **Worksheet**. +## Validation -- **PRDs are Sagas**: `flow:prd` acts as the **Orchestrator**, creating a "Master Roadmap" (Sagas) that groups multiple granular flows (Chapters). -- **Deep Research First**: Do NOT defer research to implementation "chapters." ALL analysis, codebase investigation, and architectural decisions MUST be completed during the PRD and Planning phases. -- **Refinement Gate**: You MUST run `flow:refine` autonomously and iteratively until the plan is **Zero-Ambiguity**. A "Ready" plan contains: - - **Worksheet Granularity**: Specific files, exact line numbers, and code samples for every logic change. - - **Itemized Todo List**: A step-by-step checklist that a "stateless" or "low-context" executor can follow to succeed 100% correctly without further questions. -- **Agent Autonomy**: You (the agent) are responsible for determining when a plan is granular enough. Do NOT ask the user if refinement is done; iterate until technical completeness is achieved. - -## Core Concepts - -### Flows - -A flow is a logical unit of work (feature or bug fix) backed by a Beads **Epic**. Each flow has: - -- **ID format**: `shortname` (e.g., `auth`) — MUST match the Beads Epic ID prefix. -- **Location**: `.agents/specs/{flow_id}/` -- **Files**: spec.md (synchronized view), metadata.json, learnings.md (synced from notes) - -### Status Markers (Markdown Sync) - -- `[ ]` - Pending/New (Beads: `open`) -- `[~]` - In Progress (Beads: `in_progress`) -- `[x]` - Completed (Beads: `closed`) -- `[!]` - Blocked (Beads: `blocked`) -- `[-]` - Skipped (Beads: `deferred` / `closed:skipped`) - -### Beads Integration - -Flow supports two persistence modes: - -- **Official Beads (`bd`)** - default -- **No Beads** - degraded mode for planning, docs, and lightweight local work - -### Beads Sync Policy - -Read `.agents/beads.json` before running backend export, git-add, or Dolt operations. Default Flow setup writes: - -- `bdConfig.no-git-ops: true` -- `bdConfig.export.auto: false` -- `bdConfig.export.git-add: false` -- `syncPolicy.flowSyncAfterMutation: true` -- `syncPolicy.autoExport: false` -- `syncPolicy.autoGitAdd: false` -- `syncPolicy.allowDoltPush: false` - -Do not run `bd dolt push` unless the user explicitly requests it or `.agents/beads.json` sets `syncPolicy.allowDoltPush` to `true` and opts in via `dolt.push`. - -## Universal File Resolution Protocol - -**To locate files within Flow context:** - -1. **Project Index**: `.agents/index.md` -2. **Flow Registry**: `.agents/flows.md` -3. **Flow Index**: `.agents/specs/{flow_id}/index.md` - -**Default Paths:** - -- Product: `.agents/product.md` -- Tech Stack: `.agents/tech-stack.md` -- Workflow: `.agents/workflow.md` -- Patterns: `.agents/patterns.md` -- Knowledge Base: `.agents/knowledge/` -- Knowledge Index: `.agents/knowledge/index.md` -- Beads Config: `.agents/beads.json` - -## Workflow Commands - -| Gemini CLI / OpenCode | Purpose | -|------------------------|---------| -| `/flow:setup` | Initialize project with context files and Beads | -| `/flow:prd` | **Orchestrator**: Create Beads **Epics** and Master Roadmap | -| `/flow:plan` | **Planner**: Create Beads **Tasks** and sync to spec.md | -| `/flow:sync` | **Syncer**: Bridge Beads state (notes/status) to Markdown | -| `/flow:refine` | **Refiner**: Expand coarse tasks into implementation worksheets | -| `/flow:implement` | **Executor**: Execute tasks using TDD + Beads claim/note flow | -| `/flow:status` | Display progress overview from Beads | -| `/flow:archive` | Archive completed flow and elevate patterns | - - - -## Task Workflow (TDD) - Beads-First - -**See `references/discipline.md` for iron laws, rationalization tables, and red flags.** - -1. **Select task** from the active backend's ready queue (`bd ready`). -2. **Mark in progress** and claim the task (`bd update --claim`). -3. **Investigate & Note**: Record findings/decisions with `bd note "..."`. -4. **Write failing tests** (Red phase) - MUST confirm failure for right reason. -5. **Implement** minimal code to pass (Green phase) - MUST confirm all tests pass. -6. **Refactor** with test safety — must stay green. -7. **Commit** with format: `(): `. -8. **Close task** in Beads with the commit reference (`bd close --reason "[abc1234] Done"`). -9. **Sync to markdown**: Run `/flow:sync` to update spec.md and learnings.md. - - - - - -**CRITICAL:** Never write `[x]`, `[~]`, `[!]`, or `[-]` markers to spec.md manually. Beads is the source of truth. Run `/flow:sync` after Beads state changes when `syncPolicy.flowSyncAfterMutation` is enabled, and never run export, auto-stage, or Dolt push operations unless `.agents/beads.json` allows them. - -**CRITICAL:** Read `.agents/workflow.md` before planning or implementation and prefer the repo's canonical commands there. If the repo clearly has better aggregate commands than the workflow currently documents, refresh the workflow or capture the correction in learnings/knowledge. - -**CRITICAL:** Be collaborative and constructive. Never use dismissive ownership-deflecting language such as "not my issue" or "not caused by my change." If unrelated failures block progress, describe them factually, offer the smallest helpful next step, and ask the user how to prioritize. - -**CRITICAL:** Make minimal targeted changes. Do not silently descope, take shortcuts because the task is messy, or make unrelated opportunistic edits without approval. - - - - - -### TDD Task Validation Checkpoint - -Before marking a task complete, verify: - -- [ ] Failing test was confirmed to fail for the RIGHT reason before implementation -- [ ] All tests pass after implementation (not just the new one) -- [ ] Coverage target (>80%) was checked with actual numbers -- [ ] Task was closed in Beads with the commit SHA (`bd close --reason "[abc1234]..."`) -- [ ] `/flow:sync` was run to update spec.md -- [ ] Commit message follows `(): ` format - - - -## Knowledge Flywheel (Synthesis Mandate) - -You are responsible for the entire knowledge lifecycle. It is NOT a manual copy-paste; it is a **Synthesis**. - -1. **Capture**: After each task, append discoveries to the flow's `learnings.md`. -2. **Elevate**: At phase/flow completion, autonomously identify reusable patterns and move them to `.agents/patterns.md`. -3. **Synthesize**: During sync and archive, integrate learnings directly into cohesive, logically organized knowledge base chapters in `.agents/knowledge/` (e.g., `architecture.md`, `conventions.md`). - - **Update the State**: Revise chapters to reflect the *current* authoritative state of the codebase. - - **Do NOT Outline History**: Your goal is to produce a formal, up-to-date guide for future agents, not a log of past activities. -4. **Inherit**: New flows MUST read `patterns.md` and scan `.agents/knowledge/` chapters before planning. - -Treat repeated user corrections or visible frustration as high-signal workflow gaps. Capture them in `learnings.md`, elevate them into `.agents/patterns.md`, and refine `.agents/skills/flow-memory-keeper/SKILL.md` (if present) so the same miss does not recur. - -## The Cleanup Mandate - -**CRITICAL:** The `.agents/` directory must be in its most authoritative and implementation-ready state. - -- **Knowledge Re-synthesis**: Consolidate `.agents/knowledge/` into a single, unified, authoritative "Current State" guide. Focus on "how," not "why" or history. -- **Spec & Beads Integrity**: Audit all flows in `.agents/specs/`. Verify task status against SOURCE CODE. Sync status with Beads (create if missing). -- **Archive Requirement**: Every completed flow MUST be archived and moved out of the `specs/` folder following the archive policy. -- **Artifact Consolidation**: Synthesize stale `.agents/research/` and `.agents/plans/` into active specs or knowledge chapters. -- **Pattern Optimization**: Reorganize, index, and synthesize `.agents/patterns.md` and `learnings.md` into high-fidelity guidance. - - - -## Phase Completion Protocol - -**No completion claims without fresh verification evidence.** See `references/discipline.md`. - -When a phase completes: - -1. **Run full test suite** — read output, confirm 0 failures -2. **Verify coverage** for phase files — confirm with actual numbers -3. **Dispatch code review** (recommended) — see `references/review.md` -4. **Create checkpoint commit** -5. Propose manual verification steps -6. Await user confirmation -7. Record checkpoint in Beads using the active backend's comment/note mechanism -8. Sync to markdown: run `/flow:sync` (MANDATORY) - - - - - -### Phase Completion Validation Checkpoint - -Before claiming a phase is complete, verify: - -- [ ] Full test suite was run and output was read (not assumed passing) -- [ ] Coverage was verified with actual numbers for phase files -- [ ] `/flow:sync` was run after Beads state change (MANDATORY) -- [ ] No spec.md markers were written manually - - - -## Superpowers Protocol (MANDATORY) - -When Superpowers skills are available, the following protocols MUST be followed. -If a referenced companion skill is unavailable in the current host, execute the same protocol inline instead of skipping it: - -1. **Brainstorming & Planning Overrides:** - - All brainstorming sessions (`superpowers:brainstorming`) MUST write their results to `.agents/specs//spec.md`. - - All implementation plans (`superpowers:writing-plans`) MUST be written to `.agents/specs//spec.md`. - - **NEVER** use `docs/superpowers/` for Flow-related artifacts. - - If a skill tries to use a default path, you MUST intercept and redirect to `.agents/specs//`. - - Do not declare PRD or planning work complete while obvious research gaps remain. - - Before approving a plan for execution, you MUST invoke the iterative refinement gate: ask "Do I have enough task information written for this PRD/flow to complete it correctly in the first pass?". If not, you MUST run `/flow:refine` (following the **Iteration Iron Law** in `references/refine.md`) until the plan is implementation-ready with concrete file targets, line numbers, and code samples. - -2. **Implementation Orchestration:** - - When running `/flow:implement`, you MUST explicitly recommend the "Subagent-Driven" approach to the user if `superpowers:subagent-driven-development` is available. - - You MUST use `superpowers:subagent-driven-development` to orchestrate the implementation of tasks. - - If the subagent workflow is unavailable, execute the same TDD, review, and context-preservation protocol in single-agent mode. - - Before delegating, you MUST ensure the task has undergone iterative refinement. Preserve subagent context by passing the relevant spec or PRD, patterns, knowledge chapters, learnings, affected files, and verification requirements. - -3. **Self-Review & Quality Gate:** - - Before finalizing any PRD (`/flow:prd`) or Plan (`/flow:plan`), you MUST invoke `code-reviewer` (or use the internal `Spec Review Loop`) to validate the artifacts against project patterns and requirements. - - For PRDs, ensure they follow the "Master Roadmap" structure. - - For Plans, ensure they are "Unified Specs" (Requirements + TDD Tasks). - -4. **TDD & Verification:** - - Always use `superpowers:test-driven-development` for task implementation. - - Always use `superpowers:verification-before-completion` before closing a task in Beads or marking it complete. - - If those skills are unavailable, follow the same TDD and verification discipline inline. The process remains mandatory. - -## Proactive Behaviors - -When Flow skill is active: - -- **Check Hook Context First**: ALWAYS scan `` for `## Flow Environment Context`. Use the injected **Flow Root**, **Beads Backend**, and **Canonical Commands** as authoritative ground truth. Skip manual discovery steps if this information is present. -- **Check for resume state** at session start if hook context is missing. -- **Detect the active Beads backend** (if not in hook context) and load its current context. -- Scan `knowledge/index.md` for relevant past learnings when starting a new flow. -- Prompt for learnings capture after tasks. -- Suggest pattern elevation at phase completion. -- If `.agents/skills/flow-memory-keeper/SKILL.md` exists, invoke it for sync, archive, finish, and failure/refinement work. -- If the user repeats a correction or sounds frustrated about something being forgotten, treat that as mandatory knowledge capture rather than optional polish. -- Warn if tech-stack changes without documentation. -- Enforce `/flow:sync` after Beads state changes when `syncPolicy.flowSyncAfterMutation` is enabled. -- Do not run `bd dolt push` unless the user explicitly asks or `.agents/beads.json` opts in with `syncPolicy.allowDoltPush`. -- Prefer canonical repo commands (setup, lint, test, typecheck, verify) as defined in the **Core Project Truths** section of the hook context or in `.agents/workflow.md`. -- Treat repeated reminders like "use make lint" or "don't forget to test" as workflow failures that must be captured and elevated. -- **Mandatory Superpowers Integration:** If Superpowers is detected, all workflows (PRD, Plan, Implement) MUST follow the **Superpowers Protocol** above. -- Invoke `flow:apilookup` proactively for external API/docs/version/migration questions. +- For planning: verify the plan is decision-complete before presenting it. +- For implementation: verify red-green-refactor evidence, full relevant tests, and Beads task closure before claiming completion. +- For sync/status: read backend state first and report drift instead of guessing. +- For this repository: run `make validate-skills` and `make validate-codex-manifest` after skill or command changes. ## References Index -For detailed instructions and directives for specific flow commands, refer to the following documents in `references/`: - -- **[Setup](references/setup.md)** - `/flow:setup` -- **[PRD](references/prd.md)** - `/flow:prd` -- **[Plan](references/plan.md)** - `/flow:plan` -- **[Refine](references/refine.md)** - `/flow:refine` -- **[Implement](references/implement.md)** - `/flow:implement` -- **[Sync](references/sync.md)** - `/flow:sync` -- **[Status](references/status.md)** - `/flow:status` -- **[Revert](references/revert.md)** - `/flow:revert` -- **[Validate](references/validate.md)** - `/flow:validate` -- **[Revise](references/revise.md)** - `/flow:revise` -- **[Archive](references/archive.md)** - `/flow:archive` -- **[Task](references/task.md)** - `/flow:task` -- **[Docs](references/docs.md)** - `/flow:docs` -- **[Research](references/research.md)** - `/flow:research` -- **[Refresh](references/refresh.md)** - `/flow:refresh` -- **[Finish](references/finish.md)** - `/flow:finish` -- **[Review](references/review.md)** - `/flow:review` -- **[Discipline](references/discipline.md)** - TDD, debugging, and verification iron laws - - - -## Companion Skills - -These Flow skills enhance specific phases of development. They activate automatically based on context, but can also be invoked explicitly. - -### Thinking Tools - -- **`flow:challenge`** — Use when evaluating claims, reviewing feedback, or when agreement feels reflexive. Forces structured critical reassessment. -- **`flow:consensus`** — Use when evaluating decisions with multiple valid approaches. Rotates through advocate/critic/neutral stances. Sequential mode for bounded decisions, subagent mode for high-stakes architectural choices. -- **`flow:deepthink`** — Use when a problem resists quick answers or investigation is going in circles. Tracks hypothesis, evidence, and confidence level to prevent circular reasoning. -- **`flow:perspectives`** — Shared foundation providing stance prompts and critical thinking frameworks. Loaded automatically by other companion skills. - -### Analysis Tools - -- **`flow:tracer`** — Use for systematic code exploration: execution traces, dependency mapping, and data flow analysis. Start at a known point, follow connections outward, build a map. -- **`flow:docgen`** — Use for systematic documentation generation with progress tracking. File-by-file analysis ensuring complete coverage. -- **`flow:apilookup`** — Use for documentation lookups. Checks local skill references first, then targets known URLs, then falls back to web search. -- **`flow:refine`** — Use (via `references/refine.md`) when a PRD or spec exists but the task details are still too coarse for reliable first-pass implementation. -- **`integrating-agent-platforms`** — Use for host plugin, extension, marketplace, cache, and update behavior. -- **`presenting-install-menus`** — Use when optional tooling should be offered with concise menu-driven choices. - -### Reviewer Personas +- [Setup](../flow-setup/SKILL.md) +- [Planning](../flow-planning/SKILL.md) +- [Execution](../flow-execution/SKILL.md) +- [Sync and Status](../flow-sync-status/SKILL.md) +- [Completion](../flow-completion/SKILL.md) +- [Discipline](references/discipline.md) -These can be dispatched as specialized subagents during code review or design evaluation: - -- **`flow:devils-advocate`** — Adversarial reviewer applying critic stance. Surfaces risks and untested assumptions. -- **`flow:security-auditor`** — OWASP-informed security review. Checks injection, auth, data exposure, input validation, dependencies. -- **`flow:architecture-critic`** — Evaluates structural quality: boundaries, coupling, cohesion, testability, simplicity. -- **`flow:performance-analyst`** — Identifies bottlenecks: query patterns, memory, I/O, caching, concurrency, resource lifecycle. - -### When to Use During Superpowers Workflows - -| Superpowers Skill | Companion Skills | -| ----------------- | ---------------- | -| brainstorming | `consensus` for approach evaluation, `challenge` if convergence is too fast, `architecture-critic` for structural implications | -| systematic-debugging | `tracer` for systematic exploration, `deepthink` if hypothesis testing stalls | -| requesting-code-review | `devils-advocate`, `security-auditor`, `architecture-critic`, `performance-analyst` as specialized reviewers | -| receiving-code-review | `challenge` to evaluate feedback before implementing | -| writing-plans | `flow:refine` to expand coarse tasks, `consensus` for architectural decisions, `architecture-critic` for structural quality | - - - -## Official References - -- -- -- -- -- - -## Shared Styleguide Baseline - -- Use shared styleguides for generic language/framework rules to reduce duplication in this skill. -- [General Principles](https://github.com/cofin/flow/blob/main/templates/styleguides/general.md) -- Keep this skill focused on tool-specific workflows, edge cases, and integration details. - - ## Example -Add example instructions here. - +User: "Use Flow to implement the current spec." + +Action: load `flow-execution`, claim a ready Beads task, add investigation notes, follow TDD, close the task with evidence, then sync according to policy. diff --git a/skills/flow/agents/openai.yaml b/skills/flow/agents/openai.yaml index 235214b..8bb757e 100644 --- a/skills/flow/agents/openai.yaml +++ b/skills/flow/agents/openai.yaml @@ -1,3 +1,3 @@ interface: display_name: "Flow" - short_description: "Spec-first planning, refined tasking, TDD implementation, and knowledge capture for `.agents/` projects" + short_description: "Router for Flow lifecycle skills, Beads-backed context, and .agents workflows" diff --git a/skills/gcp/SKILL.md b/skills/gcp/SKILL.md index 1a74e65..a14db7a 100644 --- a/skills/gcp/SKILL.md +++ b/skills/gcp/SKILL.md @@ -1,6 +1,6 @@ --- name: gcp -description: "Auto-activate for gcloud commands, .gcloudignore, app.yaml. Google Cloud Platform expert: gcloud CLI, IAM, service accounts, Cloud Storage, Pub/Sub, BigQuery, Vertex AI. Use when: managing GCP resources, scripting gcloud commands, or configuring any GCP service. Not for AWS, Azure, or non-GCP cloud providers." +description: "Use when managing Google Cloud resources, editing .gcloudignore or app.yaml, scripting gcloud commands, configuring IAM, service accounts, Cloud Storage, Pub/Sub, BigQuery, Vertex AI, or GCP services." --- # Google Cloud Platform (GCP) Skill diff --git a/skills/gcp/agents/openai.yaml b/skills/gcp/agents/openai.yaml new file mode 100644 index 0000000..a7abd32 --- /dev/null +++ b/skills/gcp/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Google Cloud Platform" + short_description: "gcloud, IAM, service accounts, storage, Pub/Sub, BigQuery, and GCP setup" diff --git a/skills/gke/SKILL.md b/skills/gke/SKILL.md index e0529c9..dc4e562 100644 --- a/skills/gke/SKILL.md +++ b/skills/gke/SKILL.md @@ -1,6 +1,6 @@ --- name: gke -description: "Auto-activate for kubectl commands, k8s/ directory, Helm charts. Kubernetes on GCP expertise for GKE. Produces Kubernetes deployments, Helm charts, cluster configurations, GPU/TPU workloads, AlloyDB/Cloud SQL Auth Proxy sidecars, and batch job patterns for GKE on GCP. Use when: running kubectl, Helm charts, pod/node pool management, workload identity, Kubernetes deployments, cluster scaling, GPU node pools, database sidecars, or any GKE troubleshooting. Not for Cloud Run (see cloud-run), generic Kubernetes outside GCP, or local k8s (minikube/kind)." +description: "Use when working with GKE, kubectl, Kubernetes manifests, k8s directories, Helm charts, node pools, workload identity, cluster scaling, GPU nodes, database sidecars, or GKE troubleshooting." --- # Google Kubernetes Engine (GKE) diff --git a/skills/gke/agents/openai.yaml b/skills/gke/agents/openai.yaml new file mode 100644 index 0000000..f601910 --- /dev/null +++ b/skills/gke/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "GKE" + short_description: "Google Kubernetes Engine clusters, workloads, Helm, kubectl, security, and scaling" diff --git a/skills/granian/SKILL.md b/skills/granian/SKILL.md index 6804881..ca5ebc2 100644 --- a/skills/granian/SKILL.md +++ b/skills/granian/SKILL.md @@ -1,6 +1,6 @@ --- name: granian -description: "Auto-activate for granian imports, granian CLI commands, ASGI/WSGI/RSGI server configuration. Granian Rust-based ASGI server: worker configuration, threading model, SSL, HTTP/2, backpressure. Produces granian CLI invocations, worker/thread tuning, and deployment configurations. Use when: deploying ASGI apps with granian, configuring workers/threads, setting up SSL, or replacing uvicorn. Prefer granian over uvicorn for all production deployments." +description: "Use when deploying ASGI, WSGI, or RSGI apps with Granian, editing granian CLI commands, worker or thread settings, SSL, HTTP/2, backpressure, or replacing uvicorn for production." --- # Granian Server Skill diff --git a/skills/granian/agents/openai.yaml b/skills/granian/agents/openai.yaml new file mode 100644 index 0000000..88867dd --- /dev/null +++ b/skills/granian/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Granian" + short_description: "Granian ASGI/WSGI/RSGI deployment, worker, thread, SSL, and HTTP settings" diff --git a/skills/htmx/SKILL.md b/skills/htmx/SKILL.md index 6ea05c7..f02d8d1 100644 --- a/skills/htmx/SKILL.md +++ b/skills/htmx/SKILL.md @@ -1,6 +1,6 @@ --- name: htmx -description: "Auto-activate for hx-* attributes in HTML files. Expert knowledge for HTMX hypermedia development. Use when: building hypermedia-driven apps with partial HTML responses, using `hx-` attributes, or rendering `.html` templates. Not for React/Vue/Angular SPAs or full client-side rendering." +description: "Use when editing hx-* attributes, building HTMX hypermedia flows, returning partial HTML responses, setting HTMX response headers, or rendering server-side .html templates." --- # HTMX Skill diff --git a/skills/htmx/agents/openai.yaml b/skills/htmx/agents/openai.yaml new file mode 100644 index 0000000..bba0dfe --- /dev/null +++ b/skills/htmx/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "HTMX" + short_description: "HTMX attributes, partial HTML responses, server headers, and templates" diff --git a/skills/inertia/SKILL.md b/skills/inertia/SKILL.md index 675f29b..f98dd6d 100644 --- a/skills/inertia/SKILL.md +++ b/skills/inertia/SKILL.md @@ -1,6 +1,6 @@ --- name: inertia -description: "Auto-activate for inertia imports, createInertiaApp. Expert knowledge for Inertia.js with Litestar backend. Use when building SPAs with server-side routing, handling Inertia responses, managing page components, or integrating litestar-vite with Inertia. Produces Inertia.js page components with server-side routing and Litestar backend integration. Not for traditional SPAs without server-side routing or non-Litestar backends." +description: "Use when building Inertia.js apps, editing createInertiaApp, server-side routed SPAs, Inertia protocol responses, page components, shared props, or Litestar/Inertia integrations." --- # Inertia.js Skill diff --git a/skills/inertia/agents/openai.yaml b/skills/inertia/agents/openai.yaml new file mode 100644 index 0000000..560e8c8 --- /dev/null +++ b/skills/inertia/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Inertia.js" + short_description: "Inertia pages, protocol responses, Litestar integration, and server-routed SPAs" diff --git a/skills/integrating-agent-platforms/SKILL.md b/skills/integrating-agent-platforms/SKILL.md index 2ae6da0..14c3a79 100644 --- a/skills/integrating-agent-platforms/SKILL.md +++ b/skills/integrating-agent-platforms/SKILL.md @@ -1,6 +1,6 @@ --- name: integrating-agent-platforms -description: Use when installing, updating, packaging, or troubleshooting Flow-like integrations across Claude Code, Gemini CLI, Codex CLI, OpenCode, or Google Antigravity +description: "Use when installing, updating, packaging, or troubleshooting Flow integrations across Claude Code, Gemini CLI, Codex CLI, OpenCode, Cursor, VS Code/Copilot, OpenClaw, or Google Antigravity." --- # Integrating Agent Platforms diff --git a/skills/integrating-agent-platforms/agents/openai.yaml b/skills/integrating-agent-platforms/agents/openai.yaml new file mode 100644 index 0000000..c0e1fdc --- /dev/null +++ b/skills/integrating-agent-platforms/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Agent Platform Integration" + short_description: "Flow packaging, installation, update, marketplace, and host integration behavior" diff --git a/skills/ipc/SKILL.md b/skills/ipc/SKILL.md index afe8e4a..1546565 100644 --- a/skills/ipc/SKILL.md +++ b/skills/ipc/SKILL.md @@ -1,6 +1,6 @@ --- name: ipc -description: "Auto-activate for shared memory, ring buffer, SPSC/MPMC patterns. Zero-copy IPC patterns: shared memory regions, SPSC/MPMC ring buffers, platform sync primitives, notification mechanisms, and cross-process coordination. Use when implementing IPC primitives or high-performance data transfer. Not for network IPC (gRPC, REST) or message queues." +description: "Use when implementing inter-process communication, shared memory regions, SPSC or MPMC ring buffers, zero-copy data transfer, platform synchronization primitives, or process notification mechanisms." --- # IPC (Inter-Process Communication) diff --git a/skills/ipc/agents/openai.yaml b/skills/ipc/agents/openai.yaml new file mode 100644 index 0000000..fac19e7 --- /dev/null +++ b/skills/ipc/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "IPC" + short_description: "Zero-copy IPC, shared memory, ring buffers, sync primitives, and notifications" diff --git a/skills/makefile/SKILL.md b/skills/makefile/SKILL.md index c935bd0..40fb827 100644 --- a/skills/makefile/SKILL.md +++ b/skills/makefile/SKILL.md @@ -1,6 +1,6 @@ --- name: makefile -description: "Auto-activate for Makefile, GNUmakefile. GNU Make patterns for uv-based Python project automation: .PHONY, targets, recipes. Use when: creating or editing a Makefile, adding development targets (install, clean, test, lint), or setting up self-documenting help. Not for CMake (see cpp), Cargo (see rust), or non-Make build systems." +description: "Use when editing Makefile or GNUmakefile, adding development targets, wiring uv commands, defining .PHONY rules, creating self-documenting help, or fixing Make recipe safety." --- # Makefile Skill diff --git a/skills/makefile/agents/openai.yaml b/skills/makefile/agents/openai.yaml new file mode 100644 index 0000000..d7c5c69 --- /dev/null +++ b/skills/makefile/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Makefile" + short_description: "GNU Make targets, self-documenting help, uv workflows, and recipe safety" diff --git a/skills/mojo-tools/SKILL.md b/skills/mojo-tools/SKILL.md index 328038f..1f3fef8 100644 --- a/skills/mojo-tools/SKILL.md +++ b/skills/mojo-tools/SKILL.md @@ -1,6 +1,6 @@ --- name: mojo-tools -description: "Flow-specific supplemental patterns for Mojo. Auto-activate for .mojo files, .🔥 files. Mojo development patterns for high-performance computing: SIMD, zero-copy Python interop, GIL-free parallelism, C FFI, and Hatch build integration. Use when: writing Mojo code, .mojo files, SIMD kernels, Python-Mojo hybrid projects, hatch-mojo build hooks, or packaging Mojo extensions into wheels. Produces high-performance Mojo code with SIMD kernels, Python interop, and Hatch build integration. Not for pure Python performance work or C extensions (see python/cpp)." +description: "Use when editing Mojo code, .mojo files, fire emoji files, SIMD kernels, Python-Mojo interop, GIL-free parallelism, C FFI, hatch-mojo build hooks, or packaging Mojo extensions." --- # Mojo (Flow Tools) diff --git a/skills/mojo-tools/agents/openai.yaml b/skills/mojo-tools/agents/openai.yaml new file mode 100644 index 0000000..e611325 --- /dev/null +++ b/skills/mojo-tools/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Mojo Tools" + short_description: "Flow supplemental Mojo patterns for SIMD, interop, FFI, packaging, and tests" diff --git a/skills/mysql/SKILL.md b/skills/mysql/SKILL.md index c0a77ad..2f6e0f4 100644 --- a/skills/mysql/SKILL.md +++ b/skills/mysql/SKILL.md @@ -1,6 +1,6 @@ --- name: mysql -description: "Auto-activate for .sql files with MySQL syntax, mysql connection strings, mysqldump. Produces MySQL/MariaDB queries, stored procedures, performance tuning, and connection patterns. Use when: writing MySQL queries, optimizing slow queries, configuring InnoDB, setting up replication, using mysql CLI, or working with MySQL connectors (Python, Node, Java). Not for PostgreSQL (see postgres), SQLite, or other databases." +description: "Use when writing MySQL or MariaDB SQL, editing MySQL-flavored .sql files, using mysql CLI, mysqldump, connection strings, InnoDB settings, replication, stored procedures, JSON, or query tuning." --- # MySQL / MariaDB diff --git a/skills/mysql/agents/openai.yaml b/skills/mysql/agents/openai.yaml new file mode 100644 index 0000000..0b69d6d --- /dev/null +++ b/skills/mysql/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "MySQL" + short_description: "MySQL and MariaDB SQL, CLI, InnoDB, replication, security, and performance" diff --git a/skills/nuxt/SKILL.md b/skills/nuxt/SKILL.md index 06ec9ff..d223629 100644 --- a/skills/nuxt/SKILL.md +++ b/skills/nuxt/SKILL.md @@ -1,6 +1,6 @@ --- name: nuxt -description: "Auto-activate for nuxt.config.ts, nuxt.config.js, .nuxt/ directory. Vue SSR framework expertise for Nuxt 3. Use when: using useFetch, useAsyncData, Nitro server routes, SSR/SSG rendering, nuxt.config.ts, or building any Nuxt application. Not for plain Vue (see vue), React (see react), or non-Nuxt Vue SSR." +description: "Use when editing Nuxt apps, nuxt.config.ts, nuxt.config.js, .nuxt directories, useFetch, useAsyncData, Nitro server routes, SSR, SSG, or Vue server rendering with Nuxt." --- # Nuxt 3 Framework Skill diff --git a/skills/nuxt/agents/openai.yaml b/skills/nuxt/agents/openai.yaml new file mode 100644 index 0000000..2353e21 --- /dev/null +++ b/skills/nuxt/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Nuxt" + short_description: "Nuxt 3 SSR, SSG, Nitro routes, config, data fetching, and Vue integration" diff --git a/skills/oracle/SKILL.md b/skills/oracle/SKILL.md index 0628ef0..b4eaa9c 100644 --- a/skills/oracle/SKILL.md +++ b/skills/oracle/SKILL.md @@ -1,6 +1,6 @@ --- name: oracle -description: "Auto-activate for cx_Oracle imports, oracledb imports, Oracle connection strings. Produces Oracle Database SQL, PL/SQL, connection configurations, and ORDS REST API patterns. Use when: working with Oracle databases, writing SQL/PL/SQL, building REST APIs with ORDS, configuring database connections, OCI drivers, Podman/Docker Oracle containers, or Oracle 26ai Free images. Not for PostgreSQL (see postgres), MySQL (see mysql), or cloud-only Oracle services without database access." +description: "Use when working with Oracle Database, Oracle SQL, PL/SQL, sqlplus, cx_Oracle, oracledb, ORDS, OCI drivers, Oracle containers, schema migrations, security, vectors, or performance tuning." --- # Oracle Database diff --git a/skills/oracle/agents/openai.yaml b/skills/oracle/agents/openai.yaml new file mode 100644 index 0000000..5db3d01 --- /dev/null +++ b/skills/oracle/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Oracle Database" + short_description: "Oracle SQL, PL/SQL, drivers, ORDS, containers, vectors, and administration" diff --git a/skills/performance-analyst/SKILL.md b/skills/performance-analyst/SKILL.md index 9d53521..c9bd7ba 100644 --- a/skills/performance-analyst/SKILL.md +++ b/skills/performance-analyst/SKILL.md @@ -1,6 +1,6 @@ --- name: performance-analyst -description: "Auto-activate when reviewing code in hot paths, evaluating database queries, assessing memory usage patterns, reviewing loop performance, checking for N+1 queries, evaluating caching strategies, or when code changes affect latency-sensitive operations. Produces bottleneck inventory with estimated impact (critical/moderate/minor), measurement recommendation for each finding, and fix priority. Use when: performance review needed, optimizing slow code, evaluating scaling bottlenecks, or assessing resource efficiency. Not for micro-optimizations on cold paths, premature optimization, or style-level concerns." +description: "Use when reviewing hot paths, slow code, database queries, N+1 risks, memory usage, loops, I/O, caching strategy, concurrency, latency-sensitive paths, or resource efficiency." --- # Performance Analyst diff --git a/skills/performance-analyst/agents/openai.yaml b/skills/performance-analyst/agents/openai.yaml new file mode 100644 index 0000000..aa19773 --- /dev/null +++ b/skills/performance-analyst/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Performance Analyst" + short_description: "Performance review for hot paths, queries, memory, caching, I/O, and scaling" diff --git a/skills/perspectives/SKILL.md b/skills/perspectives/SKILL.md index e0472bb..1095c49 100644 --- a/skills/perspectives/SKILL.md +++ b/skills/perspectives/SKILL.md @@ -1,6 +1,6 @@ --- name: perspectives -description: "Auto-activate when analyzing trade-offs, evaluating decisions, comparing approaches, playing devil's advocate, considering pros and cons, weighing options, assessing risks, reviewing assumptions, stress-testing a conclusion, identifying blind spots, or needing multiple viewpoints on a problem. Use when: any decision needs structured multi-angle analysis, a conclusion feels too comfortable, a proposal has not been challenged yet, or when a single perspective has dominated the analysis. Shared prompt library — produces stance prompts and critical thinking frameworks for use by other skills. Not typically invoked directly — loaded by challenge, consensus, and reviewer skills." +description: "Use when analyzing tradeoffs, comparing approaches, weighing options, assessing risks, stress-testing conclusions, identifying blind spots, or applying multiple viewpoints to a decision." --- # Perspectives diff --git a/skills/perspectives/agents/openai.yaml b/skills/perspectives/agents/openai.yaml new file mode 100644 index 0000000..6d116f3 --- /dev/null +++ b/skills/perspectives/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Perspectives" + short_description: "Shared stance prompts for tradeoff analysis, risks, assumptions, and decisions" diff --git a/skills/podman/SKILL.md b/skills/podman/SKILL.md index 94d06ac..43c0514 100644 --- a/skills/podman/SKILL.md +++ b/skills/podman/SKILL.md @@ -1,6 +1,6 @@ --- name: podman -description: "Auto-activate for podman commands, Containerfile. Podman expertise: rootless containers, pod management, systemd integration, and Docker CLI compatibility. Use when: running rootless containers, managing pods, using podman-compose, configuring systemd services, or working with OCI images without Docker daemon. Produces rootless container configurations, pod management, and systemd integration patterns. Not for Docker (see docker) or Kubernetes (see gke)." +description: "Use when running Podman, editing Containerfile, managing rootless containers, pods, podman-compose, systemd services, OCI images, secrets, or Docker-compatible workflows without a Docker daemon." --- # Podman diff --git a/skills/podman/agents/openai.yaml b/skills/podman/agents/openai.yaml new file mode 100644 index 0000000..c6dda58 --- /dev/null +++ b/skills/podman/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Podman" + short_description: "Rootless containers, pods, systemd units, secrets, and Docker compatibility" diff --git a/skills/postgres/SKILL.md b/skills/postgres/SKILL.md index 785a49b..fe73656 100644 --- a/skills/postgres/SKILL.md +++ b/skills/postgres/SKILL.md @@ -1,6 +1,6 @@ --- name: postgres -description: "Auto-activate for .sql files, psql commands, postgresql.conf, psycopg/asyncpg imports. Produces PostgreSQL queries, PL/pgSQL functions, indexing strategies, and connection patterns. Use when: writing PostgreSQL queries, optimizing performance, managing security/roles/RLS, configuring replication, writing PL/pgSQL functions/triggers, working with JSONB, using extensions, planning migrations, or connecting from application code. Not for MySQL (see mysql), AlloyDB-specific features (see alloydb), or application ORM patterns (see sqlalchemy)." +description: "Use when writing PostgreSQL SQL, editing .sql files, psql commands, postgresql.conf, psycopg or asyncpg code, indexes, JSONB, PL/pgSQL, extensions, roles, RLS, replication, migrations, or query tuning." --- # PostgreSQL diff --git a/skills/postgres/agents/openai.yaml b/skills/postgres/agents/openai.yaml new file mode 100644 index 0000000..ee2add2 --- /dev/null +++ b/skills/postgres/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "PostgreSQL" + short_description: "PostgreSQL SQL, psql, migrations, indexing, JSONB, PL/pgSQL, and operations" diff --git a/skills/pyapp/SKILL.md b/skills/pyapp/SKILL.md index 75ef93d..3e9342b 100644 --- a/skills/pyapp/SKILL.md +++ b/skills/pyapp/SKILL.md @@ -1,6 +1,6 @@ --- name: pyapp -description: "Auto-activate for pyapp build config. Build air-gapped, multi-architecture standalone Python executables using PyApp and uv. Use when: bundling Python runtimes for network-isolated environments, patching PyApp defaults, or compiling single-binary assets. Not for PyInstaller, cx_Freeze, or other Python packaging tools." +description: "Use when building standalone Python executables with PyApp, bundling Python runtimes, preparing air-gapped or multi-architecture binaries, patching PyApp defaults, or compiling single-binary assets." --- # PyApp Standalone Binaries diff --git a/skills/pyapp/agents/openai.yaml b/skills/pyapp/agents/openai.yaml new file mode 100644 index 0000000..68caab2 --- /dev/null +++ b/skills/pyapp/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "PyApp" + short_description: "Standalone Python executables, uv runtime bundling, and air-gapped builds" diff --git a/skills/pydantic/SKILL.md b/skills/pydantic/SKILL.md index 26a9784..853311d 100644 --- a/skills/pydantic/SKILL.md +++ b/skills/pydantic/SKILL.md @@ -1,6 +1,6 @@ --- name: pydantic -description: "Auto-activate for pydantic imports, BaseModel, BaseSettings, pydantic_settings. Pydantic v2 data validation and settings management: field validators, model validators, serialization, TypeAdapter, BaseSettings env config. Produces validated Pydantic models, settings classes, custom types, and migration-safe patterns. Use when: defining data models with validation, managing environment configuration, validating external data, or migrating from Pydantic v1 to v2. Not for msgspec Structs or dataclasses -- Pydantic has its own patterns." +description: "Use when defining Pydantic models, BaseModel, BaseSettings, pydantic_settings, field validators, model validators, serializers, TypeAdapter, settings env config, external data validation, or v1-to-v2 migration." --- # Pydantic Skill diff --git a/skills/pydantic/agents/openai.yaml b/skills/pydantic/agents/openai.yaml new file mode 100644 index 0000000..4a499b0 --- /dev/null +++ b/skills/pydantic/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Pydantic" + short_description: "Pydantic v2 models, settings, validators, TypeAdapter, and migrations" diff --git a/skills/python/SKILL.md b/skills/python/SKILL.md index 271e270..565b719 100644 --- a/skills/python/SKILL.md +++ b/skills/python/SKILL.md @@ -1,6 +1,6 @@ --- name: python -description: "Auto-activate for .py files, pyproject.toml, requirements.txt, setup.py, setup.cfg. Python project conventions and tooling: uv, ruff, mypy, typing, Cython, Mypyc. Use when: configuring Python packages, linting, type-checking, building extensions, or running scripts with uv. Produces Python project configurations with uv, ruff, mypy, and proper packaging. Not for Mojo (see mojo), Cython build details (see references), or web framework specifics (see litestar)." +description: "Use when editing Python files, pyproject.toml, requirements.txt, setup.py, setup.cfg, uv workflows, ruff, mypy, typing, packaging, scripts, Cython, or Mypyc extension builds." --- # Python Skill diff --git a/skills/python/agents/openai.yaml b/skills/python/agents/openai.yaml new file mode 100644 index 0000000..47c244a --- /dev/null +++ b/skills/python/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Python" + short_description: "Python packaging, uv, ruff, mypy, pyproject, scripts, and extension builds" diff --git a/skills/railway-tools/SKILL.md b/skills/railway-tools/SKILL.md index 22cce78..d89e228 100644 --- a/skills/railway-tools/SKILL.md +++ b/skills/railway-tools/SKILL.md @@ -1,6 +1,6 @@ --- name: railway-tools -description: "Flow-specific supplemental patterns for Railway. Auto-activate for railway.toml, railway.json, Procfile. Expert knowledge for Railway deployment platform. Use when deploying applications, configuring services, managing databases, or troubleshooting Railway deployments. Not for Heroku, Fly.io, or self-hosted deployments." +description: "Use when deploying to Railway, editing railway.toml, railway.json, Procfile, configuring Railway services, databases, workers, environment variables, or troubleshooting Railway deployments." --- # Railway Deployment (Flow Tools) diff --git a/skills/railway-tools/agents/openai.yaml b/skills/railway-tools/agents/openai.yaml new file mode 100644 index 0000000..ff376f2 --- /dev/null +++ b/skills/railway-tools/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Railway Tools" + short_description: "Flow supplemental Railway deployment, service, database, and worker patterns" diff --git a/skills/react/SKILL.md b/skills/react/SKILL.md index 1e6cde0..b5d9af2 100644 --- a/skills/react/SKILL.md +++ b/skills/react/SKILL.md @@ -1,6 +1,6 @@ --- name: react -description: "Auto-activate for .tsx, .jsx files, react imports. Expert knowledge for modern React development with TypeScript, including client components, framework-scoped server components, and upgrade-aware best practices. Use when building React components, managing state, or integrating with backend APIs. Not for Vue (see vue), Svelte (see svelte), or Angular (see angular)." +description: "Use when editing React code, .tsx or .jsx files, react imports, components, hooks, state, client components, framework-scoped server components, backend API integration, or React upgrades." --- # React Framework Skill diff --git a/skills/react/agents/openai.yaml b/skills/react/agents/openai.yaml new file mode 100644 index 0000000..80ad5eb --- /dev/null +++ b/skills/react/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "React" + short_description: "React TypeScript components, hooks, state, APIs, and framework-aware patterns" diff --git a/skills/rust/SKILL.md b/skills/rust/SKILL.md index 6182ea5..52ca25e 100644 --- a/skills/rust/SKILL.md +++ b/skills/rust/SKILL.md @@ -1,6 +1,6 @@ --- name: rust -description: "Auto-activate for .rs files, Cargo.toml, Cargo.lock. Produces Rust code with workspace architecture, async patterns, FFI bindings (PyO3/napi-rs), and error handling. Use when: writing Rust code, designing cross-platform systems, building Python extensions with PyO3/maturin, building Node/Bun extensions with napi-rs, exposing C ABI, or optimizing performance-critical paths. Not for C/C++ (see cpp) or languages that compile to WASM without Rust." +description: "Use when editing Rust files, .rs, Cargo.toml, Cargo.lock, workspaces, async code, error handling, PyO3, maturin, napi-rs, C ABI, platform support, tests, or performance-critical Rust paths." --- # Rust (Systems & Performance) diff --git a/skills/rust/agents/openai.yaml b/skills/rust/agents/openai.yaml new file mode 100644 index 0000000..aa37a0c --- /dev/null +++ b/skills/rust/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Rust" + short_description: "Rust workspaces, async, FFI, errors, testing, platform, PyO3, and napi-rs" diff --git a/skills/saq/SKILL.md b/skills/saq/SKILL.md index 1cf2e05..2845b7b 100644 --- a/skills/saq/SKILL.md +++ b/skills/saq/SKILL.md @@ -1,6 +1,6 @@ --- name: saq -description: "Auto-activate for saq imports, SAQ task queue configuration. SAQ (Simple Async Queue): async task queues, background jobs, cron scheduling, worker lifecycle. Produces SAQ task definitions, Worker setup, CronJob scheduling, and queue configuration. Use when: defining background tasks, enqueueing jobs, scheduling cron work, or managing worker lifecycle. Not for Celery, RQ, or Dramatiq -- SAQ has its own async-native patterns. For Litestar integration (SAQPlugin, DI, web UI, CLI), see flow:litestar." +description: "Use when editing SAQ task queues, saq imports, background jobs, async workers, enqueueing jobs, CronJob schedules, queue configuration, worker lifecycle, or async-native task processing." --- # SAQ (Simple Async Queue) Skill diff --git a/skills/saq/agents/openai.yaml b/skills/saq/agents/openai.yaml new file mode 100644 index 0000000..aae7e45 --- /dev/null +++ b/skills/saq/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "SAQ" + short_description: "SAQ async tasks, queues, cron jobs, workers, enqueueing, and lifecycle patterns" diff --git a/skills/security-auditor/SKILL.md b/skills/security-auditor/SKILL.md index 808fbc9..a705e28 100644 --- a/skills/security-auditor/SKILL.md +++ b/skills/security-auditor/SKILL.md @@ -1,6 +1,6 @@ --- name: security-auditor -description: "Auto-activate when reviewing code that handles authentication, authorization, user input, secrets, API keys, database queries, file uploads, session management, or external API calls. Produces vulnerability report with OWASP category, severity (Critical/High/Medium/Low), attack vector description, and recommended fix for each finding. Use when: security review needed, assessing attack surface, checking for OWASP vulnerabilities, reviewing access control logic, or auditing data handling. Not for general code quality, business logic review, or non-security concerns." +description: "Use when reviewing authentication, authorization, user input, secrets, API keys, database queries, file uploads, session management, external API calls, OWASP risks, or data handling attack surface." --- # Security Auditor diff --git a/skills/security-auditor/agents/openai.yaml b/skills/security-auditor/agents/openai.yaml new file mode 100644 index 0000000..3ca28e8 --- /dev/null +++ b/skills/security-auditor/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Security Auditor" + short_description: "Security review for auth, input, secrets, sessions, injection, files, and APIs" diff --git a/skills/shadcn-tools/SKILL.md b/skills/shadcn-tools/SKILL.md index c987a4a..577868c 100644 --- a/skills/shadcn-tools/SKILL.md +++ b/skills/shadcn-tools/SKILL.md @@ -1,6 +1,6 @@ --- name: shadcn-tools -description: "Flow-specific supplemental patterns for shadcn/ui. Auto-activate for components.json (shadcn config), cn() utility. Tailwind component expertise for shadcn/ui. Use when: using cn() utility, Radix primitives, shadcn add, copy-paste components, component CLI, dialogs, forms, data tables, or command palettes. Not for Material UI, Chakra UI, or other component libraries." +description: "Use when editing shadcn/ui code, components.json, cn() utility, Radix primitives, shadcn add workflows, dialogs, forms, data tables, command palettes, or Tailwind component composition." --- # shadcn/ui (Flow Tools) diff --git a/skills/shadcn-tools/agents/openai.yaml b/skills/shadcn-tools/agents/openai.yaml new file mode 100644 index 0000000..ddd1219 --- /dev/null +++ b/skills/shadcn-tools/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "shadcn/ui Tools" + short_description: "Flow supplemental shadcn/ui, Radix, Tailwind, forms, dialogs, and tables" diff --git a/skills/sphinx/SKILL.md b/skills/sphinx/SKILL.md index 4598c2e..32edafb 100644 --- a/skills/sphinx/SKILL.md +++ b/skills/sphinx/SKILL.md @@ -1,6 +1,6 @@ --- name: sphinx -description: "Auto-activate for conf.py (Sphinx), .rst files, docs/source/. Produces Sphinx documentation sites with RST, autodoc, themes (Shibuya/Immaterial), and CI/CD integration. Use when: editing conf.py, reStructuredText (.rst), autodoc, readthedocs builds, Shibuya theme, Wasm extensions, VHS terminal recordings, or any Sphinx project setup. Not for MkDocs, Docusaurus, or Mintlify documentation sites." +description: "Use when editing Sphinx docs, conf.py, .rst files, docs/source, autodoc, Read the Docs builds, Shibuya or Immaterial themes, Wasm extensions, VHS terminal recordings, or Sphinx CI." --- # Sphinx Skill diff --git a/skills/sphinx/agents/openai.yaml b/skills/sphinx/agents/openai.yaml new file mode 100644 index 0000000..242062c --- /dev/null +++ b/skills/sphinx/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Sphinx" + short_description: "Sphinx docs, conf.py, RST, autodoc, themes, CI, and doc builds" diff --git a/skills/sqlalchemy/SKILL.md b/skills/sqlalchemy/SKILL.md index ca613d8..540a69f 100644 --- a/skills/sqlalchemy/SKILL.md +++ b/skills/sqlalchemy/SKILL.md @@ -1,6 +1,6 @@ --- name: sqlalchemy -description: "Auto-activate for sqlalchemy imports, mapped_column, DeclarativeBase. Produces SQLAlchemy 2.0+ ORM models, async sessions, engine configurations, and query patterns. Use when: defining SQLAlchemy models, writing ORM queries, configuring engines/sessions, using select() statements, managing relationships, or working with asyncio sessions. Not for raw SQL without ORM (see postgres/mysql), or Advanced Alchemy patterns (see advanced-alchemy)." +description: "Use when editing SQLAlchemy code, sqlalchemy imports, mapped_column, DeclarativeBase, ORM models, relationships, select() queries, async sessions, engines, events, or migrations." --- # SQLAlchemy 2.0+ ORM & Core diff --git a/skills/sqlalchemy/agents/openai.yaml b/skills/sqlalchemy/agents/openai.yaml new file mode 100644 index 0000000..4f3719f --- /dev/null +++ b/skills/sqlalchemy/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "SQLAlchemy" + short_description: "SQLAlchemy 2 models, sessions, relationships, async engines, and queries" diff --git a/skills/sqlserver/SKILL.md b/skills/sqlserver/SKILL.md index e556498..56441b3 100644 --- a/skills/sqlserver/SKILL.md +++ b/skills/sqlserver/SKILL.md @@ -1,6 +1,6 @@ --- name: sqlserver -description: "Auto-activate for T-SQL patterns, sqlcmd, SQL Server connection strings. Produces T-SQL queries, stored procedures, indexing strategies, and SQL Server connection patterns. Use when: writing T-SQL queries, optimizing execution plans, configuring SQL Server, setting up Always On AG, using sqlcmd/SSMS, or working with SQL Server connectors (Python, Node, .NET, JDBC). Not for PostgreSQL (see postgres), MySQL (see mysql), or Azure-specific managed services." +description: "Use when writing T-SQL, editing SQL Server .sql files, using sqlcmd, SQL Server connection strings, stored procedures, execution plans, indexes, Always On, JSON, security, or connector code." --- # SQL Server diff --git a/skills/sqlserver/agents/openai.yaml b/skills/sqlserver/agents/openai.yaml new file mode 100644 index 0000000..e091867 --- /dev/null +++ b/skills/sqlserver/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "SQL Server" + short_description: "T-SQL, SQL Server administration, sqlcmd, indexing, HA, JSON, and connections" diff --git a/skills/svelte/SKILL.md b/skills/svelte/SKILL.md index 6448eca..5e518a8 100644 --- a/skills/svelte/SKILL.md +++ b/skills/svelte/SKILL.md @@ -1,6 +1,6 @@ --- name: svelte -description: "Auto-activate for .svelte files, svelte.config.js. Expert knowledge for Svelte 5 development with Runes. Use when: building Svelte components (`.svelte` files), using runic states ($state, $derived), or working with SvelteKit. Not for React (see react), Vue (see vue), or Svelte 4 (this covers Svelte 5 with Runes)." +description: "Use when editing Svelte components, .svelte files, svelte.config.js, Svelte 5 runes, $state, $derived, SvelteKit, component state, or migrating away from Svelte 4 patterns." --- # Svelte 5 Framework Skill diff --git a/skills/svelte/agents/openai.yaml b/skills/svelte/agents/openai.yaml new file mode 100644 index 0000000..f21f89e --- /dev/null +++ b/skills/svelte/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Svelte" + short_description: "Svelte 5 components, runes, SvelteKit, config, and migration patterns" diff --git a/skills/tailwind/SKILL.md b/skills/tailwind/SKILL.md index e7deb51..ffebf5a 100644 --- a/skills/tailwind/SKILL.md +++ b/skills/tailwind/SKILL.md @@ -1,6 +1,6 @@ --- name: tailwind -description: "Auto-activate for tailwind.config.ts, tailwind.config.js, @tailwind directives. Tailwind CSS v4: utility classes, responsive design, @apply, cn(), @theme config. Use when: styling with Tailwind, writing utility classes, configuring Tailwind v4, or building responsive layouts with Shadcn/ui. Not for Bootstrap, plain CSS, or CSS-in-JS solutions." +description: "Use when styling with Tailwind CSS, editing tailwind.config.ts, tailwind.config.js, @tailwind directives, utility classes, responsive layouts, @apply, cn(), @theme config, dark mode, or forms." --- # Tailwind CSS v4 Skill diff --git a/skills/tailwind/agents/openai.yaml b/skills/tailwind/agents/openai.yaml new file mode 100644 index 0000000..7be103a --- /dev/null +++ b/skills/tailwind/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Tailwind CSS" + short_description: "Tailwind v4 utilities, config, @theme, responsive design, dark mode, and forms" diff --git a/skills/tanstack/SKILL.md b/skills/tanstack/SKILL.md index 2b78022..33ff9f0 100644 --- a/skills/tanstack/SKILL.md +++ b/skills/tanstack/SKILL.md @@ -1,6 +1,6 @@ --- name: tanstack -description: "Auto-activate for @tanstack/ imports, useQuery, createRouter. Produces TanStack Router, Query, Table, and Form configurations for React applications. Use when: using useQuery, createRouter, React Query, TanStack Table, file-based routing, data fetching, or SPA state management. Not for non-React frameworks (see vue/svelte/angular) or react-router (TanStack Router is different)." +description: "Use when editing TanStack code, @tanstack imports, useQuery, createRouter, React Query, TanStack Router, Table, Form, Store, file-based routing, data fetching, or SPA state management." --- # TanStack Ecosystem diff --git a/skills/tanstack/agents/openai.yaml b/skills/tanstack/agents/openai.yaml new file mode 100644 index 0000000..f78a565 --- /dev/null +++ b/skills/tanstack/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "TanStack" + short_description: "TanStack Router, Query, Table, Form, Store, and React data workflows" diff --git a/skills/terraform/SKILL.md b/skills/terraform/SKILL.md index b61a5b4..0e567ad 100644 --- a/skills/terraform/SKILL.md +++ b/skills/terraform/SKILL.md @@ -1,6 +1,6 @@ --- name: terraform -description: "Use when creating, adopting, refactoring, or operating Terraform configurations, especially on Google Cloud. Applies to `*.tf`, `.terraform.lock.hcl`, `terragrunt.hcl`, and `terraform` workflows involving repo layout, root modules, backends/state, workspaces versus directories, brownfield import/export, CI plan/apply pipelines, testing, and policy validation." +description: "Use when creating, adopting, refactoring, or operating Terraform, *.tf files, .terraform.lock.hcl, terragrunt.hcl, root modules, backends, state, workspaces, imports, CI plan/apply, tests, or policy checks." --- # Terraform diff --git a/skills/terraform/agents/openai.yaml b/skills/terraform/agents/openai.yaml new file mode 100644 index 0000000..4da8763 --- /dev/null +++ b/skills/terraform/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Terraform" + short_description: "Terraform layout, GCP modules, state, imports, CI plans, tests, and policy" diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md index beb04f9..c7f9cd2 100644 --- a/skills/testing/SKILL.md +++ b/skills/testing/SKILL.md @@ -1,6 +1,6 @@ --- name: testing -description: "Auto-activate for test_*.py, *.test.ts, *.spec.ts, conftest.py, vitest.config.ts. Testing with pytest and vitest: fixtures, mocking, coverage, async testing, anyio. Use when: writing or refactoring tests, setting up fixtures/mocks, configuring coverage, or debugging test failures. Not for E2E/browser testing (Playwright/Cypress) or load testing." +description: "Use when writing or refactoring tests, editing test_*.py, *.test.ts, *.spec.ts, conftest.py, vitest.config.ts, pytest fixtures, mocks, coverage, async tests, anyio, or test failure debugging." --- # Testing Skill diff --git a/skills/testing/agents/openai.yaml b/skills/testing/agents/openai.yaml new file mode 100644 index 0000000..6df8d1f --- /dev/null +++ b/skills/testing/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Testing" + short_description: "pytest, vitest, fixtures, mocks, async tests, coverage, and failure debugging" diff --git a/skills/tracer/SKILL.md b/skills/tracer/SKILL.md index 93b77f6..0b544f4 100644 --- a/skills/tracer/SKILL.md +++ b/skills/tracer/SKILL.md @@ -1,6 +1,6 @@ --- name: tracer -description: "Auto-activate when tracing execution paths, mapping dependencies, understanding unfamiliar code, following data flow through a system, investigating how a feature works end-to-end, or when debugging requires understanding call chains. Produces an execution map showing the path from entry point to result — with file paths, function names, data transformations, and dependency relationships at each node. Use when: need to understand how code flows from entry point to result, mapping what depends on what, exploring unfamiliar codebases systematically, or when reading random files isn't building understanding. Not for reading random files hoping to build understanding — every file opened must be because the previous file pointed you there." +description: "Use when tracing execution paths, mapping dependencies, understanding unfamiliar code, following data flow, investigating end-to-end behavior, debugging call chains, or deciding which files to read next." --- # Tracer diff --git a/skills/tracer/agents/openai.yaml b/skills/tracer/agents/openai.yaml new file mode 100644 index 0000000..8943b88 --- /dev/null +++ b/skills/tracer/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Tracer" + short_description: "Execution tracing, dependency maps, data flow, call chains, and code exploration" diff --git a/skills/uvicorn/SKILL.md b/skills/uvicorn/SKILL.md index 82c7f7f..282b174 100644 --- a/skills/uvicorn/SKILL.md +++ b/skills/uvicorn/SKILL.md @@ -1,6 +1,6 @@ --- name: uvicorn -description: "Auto-activate for uvicorn imports, uvicorn CLI commands, ASGI server configuration. Uvicorn ASGI server: worker configuration, event loop selection, SSL, lifespan, logging, programmatic API. Produces uvicorn CLI invocations, Config/Server usage, and deployment configurations. Use when: deploying ASGI apps with uvicorn, configuring workers/reload, setting up SSL, or running development servers. Note: Granian is preferred over uvicorn for production workloads — see flow:granian." +description: "Use when deploying ASGI apps with uvicorn, editing uvicorn CLI commands, Config or Server usage, workers, reload, event loop selection, SSL, lifespan, logging, or development server behavior." --- # Uvicorn Server Skill diff --git a/skills/uvicorn/agents/openai.yaml b/skills/uvicorn/agents/openai.yaml new file mode 100644 index 0000000..375cd0d --- /dev/null +++ b/skills/uvicorn/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Uvicorn" + short_description: "Uvicorn ASGI deployment, workers, reload, SSL, lifespan, logging, and config" diff --git a/skills/vite/SKILL.md b/skills/vite/SKILL.md index c2381f4..49e9620 100644 --- a/skills/vite/SKILL.md +++ b/skills/vite/SKILL.md @@ -1,6 +1,6 @@ --- name: vite -description: "Auto-activate for vite.config.ts, vite.config.js. Expert knowledge for Vite build tool. Use when: configuring Vite (`vite.config.ts`), creating plugins, managing HMR (Hot Module Replacement), or asset bundling in JS/TS projects. Produces Vite build configurations, plugin setups, and HMR optimizations. Not for Webpack, Rollup, or non-Vite bundlers." +description: "Use when editing Vite projects, vite.config.ts, vite.config.js, Vite plugins, HMR, asset bundling, frontend build settings, deployment config, or Litestar/Vite integration." --- # Vite Build Tool Skill diff --git a/skills/vite/agents/openai.yaml b/skills/vite/agents/openai.yaml new file mode 100644 index 0000000..578da02 --- /dev/null +++ b/skills/vite/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Vite" + short_description: "Vite config, plugins, HMR, assets, deployments, and Litestar integration" diff --git a/skills/vue/SKILL.md b/skills/vue/SKILL.md index 5b1ba54..40136e0 100644 --- a/skills/vue/SKILL.md +++ b/skills/vue/SKILL.md @@ -1,6 +1,6 @@ --- name: vue -description: "Auto-activate for .vue files, vue.config.js. Expert knowledge for Vue 3 development with TypeScript. Use when: building Vue components (`.vue` files), using Composition API (`