When More Context Makes Agents Dumber, How Flow2Spec Offers a Better Solution

Problem with Memory‑Only Approaches

AI coding tools often try to give an Agent a large static context (e.g., AGENTS.md, CLAUDE.md, rule files, or a vector store). Adding more files mitigates the issue superficially, but the paradox remains: the more context is supplied, the harder it is for the agent to read it completely and correctly, leading to missed constraints or forgotten details.

Flow2Spec Core Idea

Flow2Spec is an open‑source agent‑engineering framework that grows a knowledge graph incrementally during development. Knowledge is not a monolithic document; it is a routable, dependency‑aware collection that the agent reads on demand.

Typical Workflow

Run flow2spec init to create an empty .Knowledge/ skeleton.

Execute f2s-doc-arch to generate a project architecture description and store it in the knowledge base.

When a real requirement arrives, the agent routes to existing knowledge.

After implementing the feature, run f2s-kb-sync to sync confirmed facts back to the knowledge base.

Subsequent similar requests read the updated knowledge progressively.

The knowledge base evolves through demand clarification, technical design, code implementation, bug fixing, knowledge sync, and commit tracking.

Knowledge‑Base Interface

The knowledge base resides under .Knowledge/ with a fixed layout:

.Knowledge/</code>
<code>  manifest-routing.json   # machine‑readable routing manifest</code>
<code>  matchers/                # keyword fragments</code>
<code>  topics/                  # topic summaries</code>
<code>  stock-docs/              # long‑form documented capabilities</code>
<code>  req-docs/                # requirement / design documents

Agents follow a deterministic read order:

manifest-routing.json → matcher → topic → topicDependencies → stock‑docs / req‑docs → source fallback

Progressive Reading Model

The four‑step model is:

Match : Read manifest-routing.json and select relevant matcher fragments, narrowing the candidate set.

Expand : After hitting a main topic, follow topicDependencies to pull in dependent topics (e.g., shared config rules, auth constraints).

Verify : Check whether the matched topic fully covers the user query, whether key dependencies are present, or whether deeper document reads or clarification are needed.

Act : Only when coverage and boundaries are clear does the agent implement, modify, or commit code; otherwise it asks for clarification.

Multi‑Dependency Capability

Each topic can declare which other topics it relies on. When a topic is matched, all declared dependencies are automatically expanded, ensuring the agent reads a complete, connected set of knowledge instead of isolated snippets.

Knowledge‑Base Correctness

Two risks are addressed:

Stale or incorrect knowledge.

Missing details discovered during source inspection.

When answering a question, the agent verifies whether the topic fully covers the answer. If not, it can invoke f2s-kb-distill to extract the new fact into the knowledge base or prompt the user to confirm an update.

Intent Recognition

The intentRecognition switch classifies user utterances:

Discussion queries (e.g., “Is this approach feasible?”) stay in conversation.

Bug‑fix commands (e.g., “Fix this bug”) trigger the fix flow.

Feature requests (e.g., “I want a new capability”) start a requirement‑clarification flow.

Users can override the automatic classification with explicit skill commands such as f2s-req-clarify, f2s-kb-feat, or f2s-kb-fix.

Full Development Loop

用户提出需求</code>
<code>  → explicit f2s-* skill / intentRecognition assistance</code>
<code>  → f2s-req-clarify (disambiguate)</code>
<code>  → f2s-req-tech (generate technical solution)</code>
<code>  → Agent reads knowledge progressively</code>
<code>  → implement code</code>
<code>  → changeTracking records progress</code>
<code>  → f2s-kb-sync syncs new knowledge</code>
<code>  → f2s-git-commit checks diff and knowledge coverage before commit

Each step leaves traceable artifacts in req-docs/, stock-docs/, topics/, manifest-routing.json, and .task/, ensuring the knowledge base evolves together with the code.

Five‑Layer Guardrails

Entry layer: declares read order and prohibitions.

Configuration layer: requires reading feature switches before any skill.

Routing layer: mandates reading manifest-routing.json before a full search.

Skill layer: each skill defines pre‑checks, confirmations, and hand‑off points.

Gate layer: checkpoints before archiving tasks, persisting knowledge, and committing code.

These layers reduce accidental intent mis‑classification and ensure that knowledge extracted from source code is fed back into the knowledge base.

Common Issues & Solutions

Large topic files can be split into focused sub‑topics linked via topicDependencies. Three complementary commands manage knowledge updates: f2s-kb-distill: automatic extraction after a source‑code lookup. f2s-kb-add <path>: bulk import of an entire module. f2s-kb-sync: batch synchronization of already‑implemented capabilities.

Target Audience & Quick Start

Best suited for medium‑to‑large, long‑lived codebases with many collaborators and extensive rule sets, especially teams using Cursor, Claude Code, or Codex. A quick 5‑minute trial can be started with: npx @double-codeing/flow2spec@latest init After initialization, explore the skill commands and keep intentRecognition enabled.

Conclusion

Flow2Spec converts static documentation into a routable, dependency‑aware, verifiable, and self‑updating knowledge graph, allowing agents to both consume and maintain project context throughout the development lifecycle.

Open‑source repository: https://github.com/Lands-1203/Flow2Spec

PPT demo: https://lands-1203.github.io/Flow2Spec/