Directory and Path Conventions

Core Boundary

.Knowledge/: Knowledge ring — business docs and machine-readable routing (architecture.md §2)
.task/: Task ring — change tracking (not inside .Knowledge/)
Config Root (.cursor/.claude/.codex): Rules ring + skills ring

See architecture.md §1 for Memory Coding four rings.

Directory Responsibilities

Path	Responsibility
`.Knowledge/stock-docs/`	L3 Architecture, final drafts, reference documents
`.Knowledge/req-docs/`	L3 Requirement clarification, technical proposals
`.Knowledge/topics/`	L2 Topic summaries (hard constraints, boundaries, pointers)
`.Knowledge/template/`	Templates for final drafts / technical proposals
`.Knowledge/index.md`	Human-readable index
`.Knowledge/manifest-routing.json`	L0 Machine-readable routing skeleton (task/topic/`topicDependencies`/`topicMetadata`)
`.Knowledge/matchers/*.json`	L1 Keyword fragments (`id/includeAny`); match reads one shard via `matcherPath`
`.Knowledge/migration-report.md`	Migration comparison table and deletion path list written by `f2s-kb-migrate`
`.task/`	Local change-tracking state, ignored by Git by default. In collaboration mode it has an extra `<developerId>/` layer; see “The two `.task/` layouts” below. It is created only when `changeTracking.*` is `true` or `f2s-req-plan` is explicitly invoked.
`Config Root/rules/`	Rule files (Cursor `.mdc`, Claude `.md`)
`Config Root/skills/`	Skill definitions (`SKILL.md`)
`Config Root/template/`	(Deprecated) No longer written to; historical directories may be cleaned up
`.codex/AGENTS.md`	Codex unified entry point and loading instructions
`flow2spec.config.json`	Project root configuration, controls `subAgent`, `switchAgentVerification`, `changeTracking` (nested object with `feat` / `fix` / `implement` sub-items)

See Usage Guide Section 1 for multi-platform references and path tables (detail maintained in a single table); the authoritative source remains Read(flow2spec.config.json).

Path Constraints

.Knowledge/topics is the knowledge routing topic layer; it is allowed and encouraged to be maintained via f2s-* skills.
f2s-kb-build reads from .Knowledge/stock-docs and updates .Knowledge/topics, .Knowledge/index.md, .Knowledge/manifest-routing.json, .Knowledge/matchers/*.json.
Implementation tasks uniformly read from .Knowledge/req-docs/*.md.
manifest-routing.json and matchers/*.json are maintained by f2s-* skill workflows; .Knowledge/manifest-matchers.json is no longer used (flow2spec init will delete legacy files).
.task/ and .Knowledge/update-check.json are local runtime state and should not be committed by default; flow2spec init non-destructively adds the corresponding .gitignore entries. Task progress is a personal working draft; the knowledge base is the shared team record.

The two `.task/` layouts

The layout depends on the resolved collaboration settings in flow2spec.config.json:

Mode	Condition	Paths
Legacy single root	`collaboration.enabled: false`, or no developerId can be resolved	`.task/todo.json`, `.task/active/`, `.task/completed/`
Isolated by developerId	`collaboration.enabled: true` (default) and an id is available	`.task/<developerId>/todo.json`, `.task/<developerId>/active/`, `.task/<developerId>/completed/`

Both layouts use the same child-directory convention: active tasks use the task name; archived tasks use <YYYYMMDD>-<task-name>.

How developerId is resolved

Flow2Spec takes the first usable value in this order:

flow2spec.config.json -> collaboration.developerId. A non-empty explicit value that cannot be normalized to ASCII fails with a clear error instead of silently falling back.
The part before @ in git config user.email.
git config user.name.
If none is available, use the legacy single root.

For Git-derived identities, a non-ASCII value becomes a stable dev-<first 8 chars of sha256> id and produces a warning. Teams should still prefer an explicit, readable id.

Why isolate local state by developer

The extra layer covers shared build machines, devcontainers, and shared workspaces. It also gives the Agent a stable TASK_ROOT boundary: continuation logic must not scan another developer’s unfinished tasks. developerId is a local path identity, not a remote account or permission system.

Migrating from the legacy layout

Flow2Spec does not move existing legacy tasks automatically because it cannot know who owns them. After the team confirms ownership, move active/ and completed/ into the intended .task/<developerId>/ directory manually.

Topic Metadata

manifest-routing.json.topicMetadata is machine-readable governance metadata for topics. It is only used for inventory, filtering, routing audits, upgrade gap checks, and reading expectations; it does not participate in matcher hits, does not decide whether a topic is read, is not a source of execution constraints, and must not drive topicId or filename changes. Execution constraints always come from explicit requirements in AGENTS.md, rules, skills, or topic bodies.

topicMetadata is independent from topicPaths, and each key must be a topicId already present in topicPaths. When creating a new topic, metadata may be written if there is clear evidence; classification alone must not create, rename, or split topics.

Field	Values	Meaning
`primary`	`feature` / `module` / `config` / `policy`	Single primary classification. Read the topic body and write the type that best represents its core content.
`tags`	Array of `feature` / `module` / `config` / `policy`	Optional secondary classes; values must not repeat `primary`.
`confidence`	`manual` / `inferred`	`manual` means human-confirmed; `inferred` means evidence-backed inference. When evidence is insufficient, do not write metadata and list it as pending confirmation in the summary.

Type meanings:

Type	Reading expectation
`feature`	Landed business or product capability background
`module`	Directory, package, module boundary, and engineering structure
`config`	Configuration items, switches, defaults, initialization parameters
`policy`	Process, rule, constraint, gate, prohibition, agent orchestration, skill step

Topic Granularity

A topic is a routing summary plus key boundaries; details belong in stock-docs/. Consider splitting into a main topic plus independently matchable sub-topics when its stock-doc exceeds 300-500 lines, matcher includeAny exceeds 12 terms, or the body spans more than 3 unrelated responsibility areas.