Team First Development

中文简介

Team First Development (TFD) is a selective Codex team-development method. It improves a bounded development result through alignment, model-role fit, focused context, and independent review.

This source tree is version 3.4.1. The v3.4.1 tag and GitHub Release are the publication evidence; a local checkout alone does not prove installation, deployment, or publication.

Use

Call the single Skill explicitly:

Use tfd:using-tfd to complete this development task.

TFD first decides whether collaboration is worth its coordination cost. Simple work stays with one Agent and does not read or write .tfd/. Work with separable professional responsibilities, or enough risk to require an independent reviewer, may use a project-configured team.

Coordinator workstreams

For TEAM, the Coordinator decomposes the bounded outcome into the minimum useful workstreams before activation. The exact confirmation proposal shows each workstream's accountable member, acceptance conditions, write scope, dependencies, handoff, and parallel or serial order.

Only the Coordinator activates members. Members do not re-delegate or create unconfirmed helper Agents. Dependency-free workstreams may run in parallel only when their write scopes do not overlap; a blocker stops its dependents, and the Coordinator integrates accepted outputs into one immutable review candidate.

Engineering contract

For every source-code or architecture change, TFD reads references/engineering-constraints.md completely before finalizing PLAN. This applies to both SOLO and team execution. The rules remain fixed; evidence depth scales with risk.

The reference is the single normative copy. Planning identifies the relevant change shape, execution carries only the applicable constraints, and review checks the complete candidate without adding a second Skill or policy engine.

Project teams

Project setup may define reusable team and member profiles:

.tfd/
├── manifest.yaml
├── product-team/
│   ├── team.yaml
│   ├── members/
│   │   ├── alice.yaml
│   │   └── bob.yaml
│   ├── receipts/                 # legacy, before Wiki initialization
│   └── wiki/
│       ├── schema.md
│       ├── raw/
│       ├── pages/
│       ├── queries/
│       ├── activity/
│       ├── index.md
│       └── log.md
└── platform-team/
    ├── team.yaml
    └── members/
        └── tingting.yaml

manifest.yaml indexes team directories. Each team.yaml contains the team name, purpose, member IDs, and an optional trace: delivery_receipt policy. Each named member has a members/<name>.yaml profile:

display_name: Alice
responsibility: Implement the agreed product scope
expected_output: A runnable and verified result
agency_role: backend-architect
runtime: codex_thread
model: gpt-5.3-codex-spark
reasoning_effort: high
skills: []

agency_role is optional frozen method provenance, independent from Runtime and model. TFD does not install or run agency-agents, synchronize personas, or bulk-import roles. skills may be empty; every listed Skill must be installed locally under its exact name.

Runtime	Execution surface	User-visible behavior
codex_spawn	spawn_agent	Child Agent in the current task
codex_thread	Codex thread/App Server	Independent sidebar task
codex_exec	codex exec	One-off CLI run

New or edited profiles require runtime. A v3.1 profile without runtime resolves to codex_spawn; TFD displays that resolution before activation and does not rewrite the profile.

Project setup drafts profiles, not Agents. For each requirement, TFD selects at most one configured team and its minimum useful member subset. A recurring cross-functional composition should be configured as its own team.

Team confirmation

Before writing profiles or creating any Agent, TFD presents the exact team proposal: outcome and scope, team identity and purpose, every member's ID, display name, optional agency_role, responsibility and expected output, exact Runtime, model, reasoning effort (or its default), Skills, eligibility evidence and source, and user-visible Runtime behavior; the proposal also names the minimum active subset and independent reviewer, and whether the action writes profiles, activates members, or both.

A generic request to form a team, silence, urgency, or permission for TFD to choose does not confirm an unseen roster. TFD waits for explicit confirmation. One confirmation may cover profile writes and immediate activation when both are named in the same proposal. Any material change to any proposal field requires renewed confirmation, including a changed outcome, acceptance condition, scope, exclusion, action mode, team identity or purpose, member identity, responsibility, output, model, Skill, active subset, or reviewer. Runtime and reasoning-effort changes also require renewed confirmation.

Profile-only setup writes the confirmed profiles and stops without creating Agents.

~/.codex/models_cache.json discovers account model candidates. It does not prove that codex_spawn, codex_thread, or codex_exec can currently start that model. TFD checks eligibility on the selected execution surface, and every configured Skill must be installed locally under its exact name.

After confirmation, TFD starts the exact runtime + model + reasoning_effort binding once and checks trusted Runtime metadata. Missing model or explicit reasoning-effort proof remains UNVERIFIED; startup failure or mismatch is not successful delivery. TFD does not automatically retry, switch Runtime, substitute a model, reduce reasoning effort, or otherwise fall back.

See plugins/tfd/examples/project-tfd for the complete minimal example.

Team Wiki

Each configured team may own one Git-native Markdown Wiki under its team directory. It follows the team when that directory is moved or archived. The LLM Wiki model has three layers:

1. raw/ preserves immutable, digest-addressed source snapshots.
2. pages/ and index.md contain maintained, interlinked knowledge with source citations.
3. log.md, queries/, and activity/ hold an append-only audit history of knowledge changes, explicit questions, and bounded work milestones.

This is not generic RAG and does not restore a task control plane. V1 has no embeddings, vector database, daemon, remote store, progress state, or recovery authority. Obsidian may be used as an optional Markdown viewer, but it has no runtime or write authority.

Knowledge confirmation

Initialization, ingest, repair, conflict resolution, and schema changes use PROPOSE -> CONFIRM -> APPLY. Before confirmation, no file under wiki/ changes. TFD displays the team, sources and digests, page differences, conflicts, index/log effects, current Wiki baseline, complete SHA-256, and 12-character fingerprint. Natural-language confirmation may cite the short fingerprint; only the complete matching digest authorizes the Guard. Any material proposal or baseline change requires renewed confirmation.

Sources are add-only. A revision creates a new digest-addressed snapshot and never overwrites an earlier version. Conflicting sourced claims remain on a disputed page until a separately confirmed resolution.

Query and work audit

An explicit user question, or an explicit member Wiki query inside authorized work, authorizes recording only that exact question, final answer, references, actor, and Wiki baseline without a second confirmation. Confirmed execution similarly authorizes only work_started, key handoff, evidence-bound review, final delivery, and explicit backfill records. Neither exception authorizes promotion into maintained knowledge.

The Guard validates actor and selected-member IDs against team.yaml, but V1 has no persistent execution token or hostile shared-host isolation. The conforming Skill invocation remains the confirmation boundary; an external directory-replacement race is outside V1 and remains UNVERIFIED.

The default long-record threshold is 1,000 Unicode code points. An answer of 1,000 remains complete in log.md; an answer of 1,001 goes under queries/ and leaves only summaries, references, digest, and link in the log. Long work events use activity/ in the same way, based on the complete allowed activity record; its concise summary may not exceed the threshold. Prompt text, hidden reasoning, complete Agent conversations, and raw tool output are never audit content.

If answering or real work succeeds but its audit append fails, TFD reports the result and audit failure separately. It does not roll back successful work or claim the record succeeded.

Lint and scale

Read-only lint checks structure, links, provenance, immutable-source history, the log hash chain and committed prefix, detail records, cross-team references, disputes, and obvious credentials. It never repairs findings automatically.

V1 is planned for roughly 100 source snapshots and hundreds of pages. A separate search design is warranted only after observed query misses, material index-maintenance cost, or a corpus that makes bounded page selection impractical—not from file count alone.

Local Guard commands

Run from plugins/tfd with Python 3.10 or newer. Proposal and record commands accept JSON on standard input when - is used:

python3 -m scripts.tfd_wiki.cli init --project-root PROJECT --team-id TEAM --actor-type user --actor-id user --at UTC
python3 -m scripts.tfd_wiki.cli validate --project-root PROJECT --team-id TEAM --proposal -
python3 -m scripts.tfd_wiki.cli apply --project-root PROJECT --team-id TEAM --proposal - --approval-digest SHA256
python3 -m scripts.tfd_wiki.cli record-query --project-root PROJECT --team-id TEAM --record -
python3 -m scripts.tfd_wiki.cli record-activity --project-root PROJECT --team-id TEAM --record -
python3 -m scripts.tfd_wiki.cli lint --project-root PROJECT --team-id TEAM

Delivery traces

Before a team initializes its Wiki, trace: delivery_receipt retains the legacy one-receipt behavior. Once the Wiki exists, final delivery is one delivery activity event and TFD does not create a duplicate receipt.

A receipt is a human-readable trace, not runtime authority or resumable state. Neither receipts nor Wiki activity restore a task database, progress state, recovery system, or management control plane.

Authority boundary

Team confirmation authorizes only the named local profile writes and/or member activation. It does not authorize installation, merge, push, tag, release, deployment, publication, external messages, destructive cleanup, privileged commands, paid actions, or scope expansion. Each keeps its normal approval boundary.

A version in a local checkout does not by itself prove installation or deployment. Use the v3.4.1 tag and GitHub Release as publication evidence.

Repository layout

plugins/tfd/.codex-plugin/plugin.json      Plugin manifest
plugins/tfd/skills/using-tfd/SKILL.md      Single user-facing Skill
plugins/tfd/skills/using-tfd/references/engineering-constraints.md
                                           On-demand engineering contract
plugins/tfd/skills/using-tfd/references/team-wiki.md
                                           On-demand Team Wiki protocol
plugins/tfd/scripts/tfd_wiki/              Standard-library Wiki Guard
plugins/tfd/examples/project-tfd/          Minimal YAML team example
scripts/test_plugin_contract.py            Package contract

Local verification

Python 3.10 or newer and PyYAML are required for tests.

python3 -m pip install -r requirements.txt
python3 -m unittest discover -s scripts -p 'test_*.py' -v
cd plugins/tfd
python3 -m unittest discover -s scripts -p 'test_*.py' -v

License

MIT