Context Map
Generated by npm run context-map. Regenerate after changing agents, skills, schemas, workflow contracts, or core commands.
How To Use This
- Start here when a session is long, resumed, or context-constrained.
- Load only the specific skill, contract, schema, or doc that matches the task.
- Treat
.flow-agentsas runtime state anddist/as generated output.
Repository Shape
| Path | Role | Purpose |
|---|---|---|
| agent-cards | canonical copy | Install/discovery cards that point at canonical agents. |
| agents | source | Canonical agent specs and routing prompts. |
| context | canonical copy | Shared contracts, routing notes, templates, and reusable guidance. |
| docs | canonical copy | Long-lived project documentation and GitHub Pages content. |
| evals | canonical copy | Static, integration, install, and behavioral eval fixtures. |
| kits | canonical copy | Project directory. |
| packaging | canonical copy | Project directory. |
| powers | canonical copy | Optional MCP/tool integration packs. |
| prompts | canonical copy | Reusable prompt entry points. |
| schemas | canonical copy | JSON Schema contracts for machine-readable workflow artifacts. |
| scripts | canonical copy | Build, validation, hook, telemetry, workflow, and import/export utilities. |
| skills | canonical copy | On-demand capability instructions and workflow primitives. |
| dist | generated | Generated bundle exports. Do not edit by hand. |
| .flow-agents | runtime | Cross-session workflow artifacts and sidecars. Not committed by default. |
Core Commands
| Use | Command |
|---|---|
| Source tree | npm run validate:source |
| Static suite | bash evals/run.sh static |
| Integration suite | bash evals/run.sh integration |
| Workflow artifacts | npm run workflow:validate-artifacts – –require-sidecars –require-critique .flow-agents/ |
| Workflow sidecars | npm run workflow:sidecar – –help |
| Context map drift | npm run context-map:check |
| Bundle build | npm run build:bundles |
Workflow Sidecars
Machine-readable workflow state lives beside Markdown artifacts in .flow-agents/<slug>/.
| Schema | Title | ID |
|---|---|---|
| backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.schema.json |
| workflow-acceptance.schema.json | Flow Agents Workflow Acceptance | https://flow-agents.dev/schemas/workflow-acceptance.schema.json |
| workflow-critique.schema.json | Flow Agents Workflow Critique | https://flow-agents.dev/schemas/workflow-critique.schema.json |
| workflow-evidence.schema.json | Flow Agents Workflow Evidence | https://flow-agents.dev/schemas/workflow-evidence.schema.json |
| workflow-handoff.schema.json | Flow Agents Workflow Handoff | https://flow-agents.dev/schemas/workflow-handoff.schema.json |
| workflow-learning.schema.json | Flow Agents Workflow Learning | https://flow-agents.dev/schemas/workflow-learning.schema.json |
| workflow-release.schema.json | Flow Agents Workflow Release Readiness | https://flow-agents.dev/schemas/workflow-release.schema.json |
| workflow-state.schema.json | Flow Agents Workflow State | https://flow-agents.dev/schemas/workflow-state.schema.json |
Primary tools: npm run workflow:sidecar, npm run workflow:validate-artifacts, scripts/hooks/stop-goal-fit.js, and scripts/hooks/workflow-steering.js.
Workflow Skills
| Skill | Source | When To Load |
|---|---|---|
| deliver | skills/deliver/SKILL.md | Delivery workflow — selected work to delivered code. Ensures pull-work + pickup-probe preflight, then chains plan-work → execute-plan → review-work → verify-work → loop on failure without requiring user interaction between cleanly determ… |
| evidence-gate | skills/evidence-gate/SKILL.md | Evaluate whether completed work is trustworthy enough for human review, merge, or release. Use after implementation, verify-work, provider checks, CI, or remediation to map acceptance criteria to evidence, inspect scope integrity, classi… |
| execute-plan | skills/execute-plan/SKILL.md | Parallel execution primitive — plan artifact path to implemented code via tool-worker (x4). Reads plan directly. Updates session file between waves. |
| fix-bug | skills/fix-bug/SKILL.md | Bug fix orchestrator — diagnose → plan-work → execute-plan → review-work → verify-work → loop. Diagnosis phase is unique to bugs, then chains the same primitives. |
| idea-to-backlog | skills/idea-to-backlog/SKILL.md | Turn raw product or technical ideas into shaped, prioritized, executable GitHub issue backlog. Use for idea intake, ideation, product shaping, spike/prototype decisions, PRD-like feature briefs, prioritization, and backlog creation befor… |
| learning-review | skills/learning-review/SKILL.md | Capture post-merge, post-deploy, or post-incident learnings and feed them back into backlog, workflow skills, tests, docs, or knowledge. Use after release readiness, post-deploy checks, retrospectives, failed gates, or repeated workflow… |
| plan-work | skills/plan-work/SKILL.md | Code planning primitive — goal + directory to structured execution plan. Delegates to tool-planner. No resume, no ideation. |
| pull-work | skills/pull-work/SKILL.md | Select ready GitHub issues from the executable backlog and prepare them for implementation. Use when choosing what to work on next, reviewing a kanban-style issue board, enforcing WIP limits, grouping issues, deciding worktree isolation,… |
| release-readiness | skills/release-readiness/SKILL.md | Decide whether evidence-backed work is ready to merge, release, deploy, or hold. Use after evidence-gate PASS, before merge/release/deploy, and for post-deploy verification planning. |
| review-work | skills/review-work/SKILL.md | Review primitive - run report-only code, security, dependency, architecture/standards, and IaC/policy critique before verification; records findings through the critique artifact/sink, currently critique.json locally. |
| tdd-workflow | skills/tdd-workflow/SKILL.md | Test-driven development — RED → GREEN → REFACTOR with git checkpoints. Wraps plan-work → execute-plan → review-work → verify-work with test-first constraints and coverage gates. |
| verify-work | skills/verify-work/SKILL.md | Verification primitive — session file path to structured evidence verdict via tool-verifier + tool-playwright. Reads acceptance criteria from plan artifact. |
Support Skills
| Skill | Source | When To Load |
|---|---|---|
| agentic-engineering | skills/agentic-engineering/SKILL.md | Eval-first execution, task decomposition, and cost-aware model routing for AI-driven development workflows. |
| browser-test | skills/browser-test/SKILL.md | Headless browser automation via Playwright — screenshots, accessibility checks, form filling, UI testing, DOM inspection. |
| builder-shape | skills/builder-shape/SKILL.md | Invoke Builder Kit shape from a raw idea or the current conversation context without requiring the user to name idea-to-backlog. Delegates shaping to idea-to-backlog, records the Builder Kit Flow Definition link, and stops at the backlog… |
| context-budget | skills/context-budget/SKILL.md | Audit token overhead across Flow Agents bundles — agent specs, skills, context files, MCP servers. Produces budget report with per-component breakdown and optimization suggestions. |
| dependency-update | skills/dependency-update/SKILL.md | Analyze and upgrade project dependencies — latest versions, security vulnerabilities, actionable update plan across all package managers. |
| design-probe | skills/design-probe/SKILL.md | Generic one-question-at-a-time design probing interview for turning unclear goals, designs, or workflow states into shared understanding before planning or execution. |
| eval-rebuild | skills/eval-rebuild/SKILL.md | Project-specific build and install commands for the eval feedback loop. Injected into eval-builder agent. Replace this skill for different build systems. |
| explore | skills/explore/SKILL.md | Parallel codebase exploration — fans out subagents to map structure, entry points, dependencies, patterns, config, and tests in one pass. |
| feedback-loop | skills/feedback-loop/SKILL.md | Verify implementation actually works. Visual changes → Playwright; integration changes → commands/tests. Run after completing builds. |
| frontend-design | skills/frontend-design/SKILL.md | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. |
| github-cli | skills/github-cli/SKILL.md | Interact with GitHub via gh CLI — PRs, issues, repos, releases, workflows, gists. |
| knowledge-capture | skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when… |
| pickup-probe | skills/pickup-probe/SKILL.md | Builder Kit work-item/docs/provider-grounded Probe specialization used at the design-probe flow step before plan-work. |
| search-first | skills/search-first/SKILL.md | Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. |
Agents
| Agent | Model | Tools | Role |
|---|---|---|---|
| dev | claude-opus-4.6-1m | 1 | Development agent for coding tasks. Writes, modifies, and validates code following existing patterns. Delegates to specialists for domain-specific research when available. |
| tool-code-reviewer | claude-sonnet-4.6-1m | 8 | Delegate to me for code quality review. Analyzes readability, maintainability, patterns, DRY compliance, and produces structured review with severity levels. Separate from verification (build/test/lint). |
| tool-dependencies-updater | agi-nova-beta-1m | 8 | Delegate to me for updating your project dependencies - checks latest versions, identifies outdated packages, and finds security advisories across npm, PyPI, Cargo, Maven/Gradle, Go, NuGet, Ruby, PHP, Swift, Dart, Docker, Helm, Terraform… |
| tool-explore-config | kimi-k2.5 | 6 | Delegate to me for project configuration inspection - finds and summarizes configuration files and environment variables within a project |
| tool-explore-deps | kimi-k2.5 | 6 | Delegate to me for Dependency analysis - parses package manifests to identify tech stack and dependencies |
| tool-explore-entry | kimi-k2.5 | 6 | Delegate to me to find the Entry point of a project - locates main files, CLI commands, API routes, and exports |
| tool-explore-patterns | kimi-k2.5 | 6 | Delegate to me for Pattern detection - identifies architectural patterns, frameworks, and coding conventions |
| tool-explore-structure | kimi-k2.5 | 6 | Delegate to me to scout out the project structure - maps directory layout and identifies key folders in a codebase |
| tool-explore-tests | kimi-k2.5 | 6 | Delegate to me to find and understand testing strategies - locates test files and understands testing strategy |
| tool-planner | claude-sonnet-4.6-1m | 7 | Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .flow-agents. No production file modifications. |
| tool-playwright | claude-sonnet-4.6-1m | 25 | Delegate to me for browser automation, testing, and debugging - loading real pages, testing navigation, checking accessibility via structured snapshots, evaluating scripts, and visual verification. Anything that would otherwise require a… |
| tool-security-reviewer | claude-sonnet-4.6-1m | 7 | Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools. |
| tool-verifier | claude-sonnet-4.6-1m | 8 | Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No productio… |
| tool-worker | claude-sonnet-4.6-1m | 1 | Delegate to me for writing and developing source code for a project. Works best when a detailed plan can be provided. NO access to web tools. Can be used in parallel for any coding tasks that require trusted access to the write and shell… |
Optional Powers
| Power | Source |
|---|---|
| dependency-checker | powers/dependency-checker/POWER.md |
| playwright | powers/playwright/POWER.md |
Packs
Pack composition is defined in packaging/packs.json. The current builder exports pack metadata in bundle catalogs, and generated install scripts support opt-in FLOW_AGENTS_PACKS filtering while leaving all packs installed by default.
| Pack | Default | Skills | Agents | Powers | Purpose |
|---|---|---|---|---|---|
| core | yes | 9 | 5 | 1 | Small default surface for reliable coding and workflow execution. |
| development | no | 17 | 9 | 1 | Development workflow depth for backlog, release, dependency, GitHub, TDD, and frontend work. |
Current Workflow State
Runtime workflow state is excluded from the committed map.
Regenerate locally with npm run context-map -- --include-runtime to include recent .flow-agents state.
Context Loading Rules
- For delivery work, load
deliver, then the specific primitive skill for the current phase. - For planning, verification, release, learning, or artifact validation, load
context/contracts/artifact-contract.mdplus the phase contract. - For unknown external APIs or libraries, use
search-firstbefore implementation. - For large or noisy sessions, prefer sidecars and this map over rereading broad docs.
- For generated exports, edit source files and rebuild instead of editing
dist/.