flowstate-mcp Package Skill

Package: @epicdm/flowstate-mcp Repository: epic-flowstate-community Path: packages/flowstate-mcp Version: 1.1.6

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Agent Operations And Memory

Use this skill for MCP tools that help agents identify themselves, coordinate work, communicate, provision subordinate agents, and persist or retrieve memory.

Tool Families

Family	Purpose
Agent inbox	Resolve an agent and return tasks, mentions, replies, approvals, and conversation items.
Agent chat/conversation	Send, read, and manage agent conversation flows.
Subordinates and provisioning	Provision/report subordinate agents and inspect health, usage, RBAC, budget, and vault status.
Collaboration/access audit	Report collaboration and access state for agents.
Agent keys	Provision and rotate agent tokens, add agents to vaults, and list keys.
Agent memory	Wrap Agent Memory Server for recall, store, search, sessions, and forget flows.
FlowState AgentMemory	Call the FlowState AgentMemory API with scoped namespaces and observation records.

Memory Model

There are two related memory integrations:

AgentMemoryTools wraps @epicdm/flowstate-agents-memory-client and AMS endpoints.
FlowStateAgentMemoryTools calls a FlowState AgentMemory HTTP API and derives namespaces from visibility and scope fields.

Do not merge their semantics without checking source. AMS working memory, long-term memory, SAGA write-through, and FlowState AgentMemory namespaces have different contracts.

Safe Usage Pattern

Resolve the agent identity or slug first.
Pass org/workspace scope explicitly for HTTP and service callers.
Recall memory before high-context tasks.
Store durable learnings only after checking whether the memory family expects working, long-term, or scoped FlowState memory.
Treat empty memory results as a possible service/config issue, not proof no knowledge exists.

Pitfalls

Some memory clients use best-effort null or empty result semantics.
Namespace derivation can throw when required scope IDs are missing.
Agent key and vault flows require unlocked vault state and caller auth context.
Generated skilllets do not explain which memory system a tool uses.

Package Skill Inventory

Package Skill Inventory: @epicdm/flowstate-mcp

Skill Map

Skill	Type	Trigger	Teaches	Dojo
`flowstate-mcp`	orchestrator	Use when touching MCP server behavior, tool contracts, package exports, or docs	Routes to runtime, CRUD, workflow, agent, RAG/document, security, troubleshooting, and maintenance skills	local-only
`flowstate-mcp-runtime-transports`	workflow	Use when running stdio/HTTP MCP, configuring env/auth, or debugging tool availability	Stdio vs HTTP, auth gate, lazy init, optional services, schema seeding, tool listing	ready-after-review
`flowstate-mcp-tool-routing-context`	reference	Use when adding or debugging MCP tools	Tool registration, dispatch, tool result envelopes, context extraction/injection, schema compatibility	ready-after-review
`flowstate-mcp-collection-schema-crud`	workflow	Use when using generic collection or schema tools	Collection CRUD/list/query/aggregate, virtual collections, list limits, schema registry, context merge	ready-after-review
`flowstate-mcp-work-planning-tools`	workflow	Use when using spec, task, roadmap, initiative, process, product, hierarchy, or assignment tools	Spec/task lifecycle, planning records, proposal/step tools, bridge contract risks	ready-after-review
`flowstate-mcp-agent-ops-memory`	workflow	Use when using agent inbox, chat, provisioning, collaboration, bootstrap, keys, or memory tools	Agent identity, inbox, subordinates, AMS memory, FlowState AgentMemory API, chat/auth expectations	ready-after-review
`flowstate-mcp-rag-documents-codebase`	workflow	Use when using RAG, document, document encryption, or codebase search tools	RAG client config, document-store bridge, semantic search, codebase filters, vault keyring composition	ready-after-review
`flowstate-mcp-security-vault-rbac`	workflow	Use when touching OAuth auth, vault, keys, service accounts, RBAC, or SAGA identity	Auth gate, per-org vault state, keyring lifecycle, RBAC proxying, service account and agent-key flows	ready-after-review
`flowstate-mcp-troubleshooting`	troubleshooting	Use when tool calls fail, docs disagree with behavior, or generated Dojo content looks misleading	Optional service absence, context/auth failures, adapter risks, stale docs, result envelope issues	local-only
`flowstate-mcp-maintenance`	maintenance	Use before changing public tools, package exports, docs, feature matrix, or Dojo content	Reverse references, tests, tool inventory, docs/matrix/Dojo sync, anti-sprawl checks	local-only

Anti-Sprawl Decision

Do not create one skill per tool class, route, exported constant, or MCP tool. The package has more than 90 detected features, but agents need a small number of composable workflows. Constants, helper functions, route names, and individual tools belong inside workflow/reference skills.

Feature Coverage

Feature Group	Covered By	Notes
Stdio and HTTP server startup	runtime-transports	Includes `mcp-server`, `httpServer`, auth gate, health/tools routes.
Server initialization and tool dispatch	tool-routing-context	Includes `FlowStateMCPServer`, tool definitions, `wrapToolResult`, OpenAI schema compatibility.
Client adapter and data layer	collection-schema-crud	Includes `ClientAdapter`, `CRUDTools`, `SchemaRegistry`, virtual collections, list limits.
Spec/task/planning/project/product hierarchy	work-planning-tools	Includes spec tools, task workflow, planning workflow, bizplan/product/hierarchy/assignment tools.
Coordinator proposal/mission/step tools	work-planning-tools, troubleshooting	Includes `ProposalService` and `StepExecutor` adapter risk.
Agent operations and memory	agent-ops-memory	Includes inbox, subordinate, provisioning, collaboration, chat, AMS, FlowState AgentMemory.
RAG/document/codebase search	rag-documents-codebase	Includes `RAGTools`, `DocumentTools`, `CodebaseSearchTools`, document-store and RAG client contracts.
Vault/RBAC/auth/keys	security-vault-rbac	Includes OAuth resource auth, vault state, member management, key provisioning, RBAC categories.
Observability, finance, Git, state, timers	work-planning-tools, maintenance, troubleshooting	Mention as active tool families; add focused skills later only if usage warrants.
Generated Dojo	troubleshooting, maintenance	Treat as prototype; not publishable without rewrite.

Deferred Skills

Separate skill per MCP tool class: defer unless a tool family becomes too large to operate from the workflow skill.
Separate observability/finance/Git skills: defer until package review shows enough repeated usage to justify standalone triggers.
Dojo publish skill: defer until existing .flowstate/dojo content is rebuilt from reviewed package skills.
Coordinator adapter repair skill: track as implementation follow-up; current skillset documents the risk.

Review Gate

Package Skills Review: @epicdm/flowstate-mcp

Verdict

Pass with fixes.

The authored skillset uses workflow-level boundaries instead of generated symbol sprawl. It captures the main MCP operating surfaces and flags the highest-risk coordinator contract issue.

Findings

Severity	Skill	Issue	Evidence	Required Fix
Critical	work-planning/troubleshooting	`step-complete` constructs `StepExecutor` through an adapter that may lack `updateAgentStatus()`	`src/server/MCPServer.ts`, coordinator `StepExecutor` contract	Repair or explicitly track before presenting step completion as fully safe
Important	all	Existing Dojo content is generated and not teaching-grade	`.flowstate/dojo/*`	Rebuild from reviewed skills
Important	runtime/security	Docs understate modern HTTP auth, vault per-org state, RBAC, agent memory, and planning tools	README, `.flowstate/docs`, source	Update docs before final Dojo publish
Important	verification	Package test suite currently has one failing vault-stats assertion; typecheck and build pass	`VaultTools.stats.test.ts`; verification run	Fix or track before Dojo publication

Coverage

Feature Group	Status	Skill
Runtime and transports	Covered	runtime-transports
Tool registration/context/result envelopes	Covered	tool-routing-context
Collection/schema CRUD	Covered	collection-schema-crud
Spec/task/planning/product/hierarchy	Covered	work-planning-tools
Agent operations and memory	Covered	agent-ops-memory
RAG/documents/codebase search	Covered	rag-documents-codebase
Auth/vault/RBAC/keys	Covered	security-vault-rbac
Drift and generated content	Covered	troubleshooting, maintenance

Dojo Publication Decision

Do not publish existing .flowstate/dojo content. Rebuild Dojo skill/course artifacts from this reviewed local skillset after verification and after the critical StepExecutor adapter risk is either fixed or tracked as an explicit known limitation.

Verification

Commands run:

yarn workspace @epicdm/flowstate-mcp test --runInBand
yarn workspace @epicdm/flowstate-mcp typecheck
yarn workspace @epicdm/flowstate-mcp build

Results:

Test failed: 95 suites passed, 2 skipped, 1 failed; 1917 tests passed, 17 skipped, 1 failed.
Failing assertion: src/tools/__tests__/VaultTools.stats.test.ts expected expiringCount to be 1, received 0.
Typecheck passed.
Build passed with existing unused external import warnings for removeRxDatabase and OpenClawClientError.

Follow-Up Work

Run package verification.
Repair or track the MCP StepExecutor adapter contract.
Fix or track the vault stats expiringCount test failure.
Update package docs to describe modern tool groups and auth/runtime behavior.
Rebuild Dojo artifacts from reviewed skills.

flowstate-epic-flowstate-community-epicdm-flowstate-mcp

Tags

Publisher

Versions

Skill