Pin the project root for this MCP session.
Useful when the MCP process was spawned with the wrong working
directory — typical symptom: ``unbound_report`` shows a project
path like ``C:\Users\<you>`` instead of the workspace you
actually opened in Cursor. Calling this tool once re-binds every
subsequent tool call to the given directory, **without** editing
``mcp.json`` or restarting Cursor.
Safe to call while UNBOUND — re-pointing at a directory is not a
role-claim and writes nothing. It only mutates in-process state.
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.
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 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/``).
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.
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 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, optionally filtered.
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 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/``.
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>/``.
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.
+33 more tools listed on main page