Filesystem vs FCoP

init_project

Initialize an FCoP project with a bundled preset team. Since 3.0.2 a fresh init produces the **v3 topology** (per spec §1.1): ``fcop/_lifecycle/{inbox,active,review,done,archive}/`` plus the retained v2 buckets ``reports/`` / ``issues/`` / ``shared/``. The superseded v2 buckets ``tasks/`` and ``log/`` are no longer created on fresh init (use ``python -m fcop migrate --to-v3`` to upgrade an existing v2 project). Writes ``fcop/fcop.json``, deposits ``LETTER-TO-ADMIN.md`` under ``fcop/``, creates the ``workspace/`` cage with a starter README (per Rule 7.5), deploys the team's three-layer docs to ``fcop/shared/`` (TEAM-README / TEAM-ROLES / TEAM-OPERATING-RULES + ``roles/{ROLE}.md``, both zh and en), and (per ADR-0006) deploys the bundled protocol rules to **four** locations so any agent host sees them: ``.cursor/rules/fcop-rules.mdc``, ``.cursor/rules/fcop-protocol.mdc``, ``AGENTS.md``, and ``CLAUDE.md``. Existing copies are archived to ``.fcop/migrations/<timestamp>/`` before being overwritten.

init_solo

Initialize an FCoP project in **Solo mode** (one AI, no dispatch). Solo mode is for projects where a single agent works directly with ADMIN. Rule 0.b still applies: the agent uses files to split itself into *proposer* and *reviewer*, even though there is no second role. Since 3.0.2 fresh init produces the **v3 topology** (per spec §1.1): ``fcop/_lifecycle/{inbox,active,review,done,archive}/`` plus retained ``reports/`` / ``issues/`` / ``shared/``. Superseded v2 buckets (``tasks/``, ``log/``) are no longer created on fresh init. Beyond ``fcop.json`` and the canonical directories, this also deposits ``fcop/LETTER-TO-ADMIN.md`` (the user manual), creates the ``workspace/`` cage with a starter README (per Rule 7.5), deploys the bundled solo three-layer docs (TEAM-README / TEAM-ROLES / TEAM-OPERATING-RULES + ``roles/ME.md``, both zh and en) to ``docs/agents/shared/``, and (per ADR-0006) drops the bundled protocol rules into ``.cursor/rules/*.mdc`` + ``AGENTS.md`` + ``CLAUDE.md``. Existing copies are archived under ``.fcop/migrations/<timestamp>/`` before being overwritten.

create_custom_team

Create an FCoP project with a custom roster of roles. Role codes can be anything — they become part of task filenames, e.g. ``TASK-20260423-001-BOSS-to-CODER.md``. Use ``validate_team_config`` first to catch illegal role codes without writing anything. Since 3.0.2 fresh init produces the **v3 topology** (per spec §1.1): ``fcop/_lifecycle/{inbox,active,review,done,archive}/`` plus retained ``reports/`` / ``issues/`` / ``shared/``. Superseded v2 buckets (``tasks/``, ``log/``) are no longer created on fresh init. Custom teams have **no bundled three-layer docs**, so ``fcop/shared/`` is left empty (apart from the project's own ``shared/README.md``). The recommended next step is to read the closest preset (``fcop://teams/<closest-preset>`` — see the ``teams/_data/README.md`` "Custom teams" section) and hand-author your own ``TEAM-README.md`` / ``TEAM-ROLES.md`` / ``TEAM-OPERATING-RULES.md`` + ``roles/{ROLE}.md`` based on it. The other init artifacts are deposited as usual: ``fcop/fcop.json``, ``LETTER-TO-ADMIN.md``, ``workspace/README.md``, plus the protocol rule files at ``.cursor/rules/*.mdc`` + ``AGENTS.md`` + ``CLAUDE.md`` (existing copies archived under ``.fcop/migrations/``).

validate_team_config

Dry-run validation for a custom team config. Use **before** ``create_custom_team`` to catch illegal role codes (Chinese characters, dashes, reserved names, duplicates) without writing anything to disk.

write_task

Create a new task file (Cold Path dispatch or formal intake only). **Not Hot Path execution.** Use when ``ADMIN`` / ``leader`` assigns work, when Cold Path fan-out dispatches subtasks, or when you were explicitly told to land a formal task. Agents **must NOT** self-dispatch without an upstream requirement (Rule 0.a.2). Subtask linking: set ``thread_key`` for thread continuity; set ``parent`` to the upstream task ID (``parent:`` frontmatter — work derivation, distinct from ``references``). Do **not** emit ``parent_task_id`` as normative output (read-only legacy alias only). File ops: write ``TASK-*.md`` under ``_lifecycle/inbox/`` (v3) or ``fcop/tasks/`` (v2). Does **not** claim, finish, or archive. The library assigns a filename of the form ``TASK-YYYYMMDD-NNN-{SENDER}-to-{RECIPIENT}.md`` with FCoP-compliant YAML frontmatter + markdown body. In v3 the recipient ``claim_task``s from inbox.

read_task

Read the full content of a task file (Hot Path pre-flight). **Before executing** on an assigned or claimed task, call this **together with** ``inspect_task`` (Rules 0.a.1 / 0.a.2). Do not mutate the workspace or dispatch from chat/memory alone. File ops: ``cat`` the file under ``_lifecycle/{stage}/TASK-*.md``, legacy ``fcop/tasks/``, or ``fcop/log/`` when archived.

list_tasks

List tasks, optionally filtered.

inspect_task

Validate a task file against FCoP grammar (Hot Path pre-flight). Run **before executing** on a claimed/assigned task, alongside ``read_task``. Catches deterministic violations agents often miss (filename ``to-DEV`` vs frontmatter ``recipient: QA``, mistyped ``protocol``, missing required fields). ``PASS`` does **not** replace reading the task body for acceptance criteria. File ops: read filename + frontmatter and validate grammar only.

archive_task

Archive a task after governance acceptance (v3: ``_lifecycle/archive/``; v2: ``log/``). **Governance action (Rule 0.a.5).** **Not** Hot Path step 4 for executors. Default actor is ``leader`` or ``ADMIN`` after accepting the paired ``REPORT-*``. Executors must **not** call this unless the task body or ``ADMIN`` explicitly authorises archive-on-completion. **Authorization:** subtasks — direct upstream or governance runtime; main tasks — ``ADMIN`` or the main-task owner only. Archive **≠** business completion (Rule 0.a.3). Does **not** run automatically after ``write_report`` or ``finish_task``. File ops: ``mv`` task (+ matched reports via ``references``) to ``_lifecycle/archive/`` or ``fcop/log/``.

archive_to_history

Deep-history cold storage after governance archive (v3 only). Moves a task already in ``_lifecycle/archive/`` (or legacy ``log/``) into ``history/YYYY-MM-DD/<task-stem>/`` with its reports — immutable, date-sharded retention. **Not** business acceptance and **not** a substitute for ``write_report`` or authorised ``archive_task``. Call ``archive_task`` first (v3: ``done/`` → ``archive/``). Main-task deep archive requires the same governance authorization as ``archive_task`` (Rule 0.a.5). File ops: ``mv _lifecycle/archive/TASK-* history/YYYY-MM-DD/<stem>/``.

bulk_archive_to_history

Migrate **all** tasks from ``_lifecycle/archive/`` into the deep history archive. This is a convenience migration tool. It iterates every task in ``_lifecycle/archive/`` and calls :func:`archive_to_history` for each one, moving each task together with its associated reports into ``history/YYYY-MM-DD/<task-stem>/``. Useful when: - A project is being upgraded and existing archived tasks need to be moved into the new date-sharded history structure. - You have just finished a manual archiving session and want to flush everything from ``_lifecycle/archive/`` into ``history/`` in one step. The ``history/`` directory is created automatically if it does not yet exist.