|
4 | 4 |
|
5 | 5 | [中文简介](README-CN.md) |
6 | 6 |
|
7 | | -Team First Development (TFD) is a selective Codex team-development method. It |
8 | | -aligns a minimum-sufficient team to the user's intended outcome, partitions |
9 | | -context by responsibility, coordinates explicit handoffs, and requires |
10 | | -independent review and evidence-backed delivery. |
| 7 | +Team First Development (TFD) is a selective Codex team-development method. |
| 8 | +It improves a bounded development result through alignment, model-role fit, |
| 9 | +focused context, and independent review. |
11 | 10 |
|
12 | 11 | This checkout is the `3.0.0` local candidate. It is not a release. |
13 | 12 |
|
14 | 13 | ## Use |
15 | 14 |
|
16 | | -Call `tfd:using-tfd` explicitly. |
| 15 | +Call the single Skill explicitly: |
17 | 16 |
|
18 | 17 | ```text |
19 | 18 | Use tfd:using-tfd to complete this development task. |
20 | 19 | ``` |
21 | 20 |
|
22 | | -TFD first decides whether collaboration is worth its coordination cost. It |
23 | | -recommends a team only when the task has separable professional |
24 | | -responsibilities or needs implementer/reviewer separation, relevant context can |
25 | | -be partitioned, and the expected benefit exceeds coordination and handoff cost. |
26 | | -Otherwise, it routes the task to one Agent. A user may still force TFD after |
27 | | -the cost is disclosed. |
| 21 | +TFD first decides whether collaboration is worth its coordination cost. |
| 22 | +Simple work stays with one Agent and does not read or write `.tfd/`. Work with |
| 23 | +separable professional responsibilities, or enough risk to require an |
| 24 | +independent reviewer, may use a project-configured team. |
28 | 25 |
|
29 | | -Simple work stays solo and session-only. The normal TFD team workflow is also |
30 | | -session-only: it does not depend on `.tfd/` and does not persist project state. |
| 26 | +## Project teams |
31 | 27 |
|
32 | | -## Optional high assurance |
| 28 | +Project setup may define reusable team and member profiles: |
33 | 29 |
|
34 | | -High-assurance state is optional, requires explicit approval, and uses the |
35 | | -Python standard-library SQLite engine at `.tfd/state.db`. It is appropriate for |
36 | | -cross-session continuation, durable decision or review evidence, multi-day or |
37 | | -materially concurrent work, elevated change risk, or an explicit request for |
38 | | -durable local state. |
| 30 | +```text |
| 31 | +.tfd/ |
| 32 | +├── manifest.yaml |
| 33 | +├── product-team/ |
| 34 | +│ ├── team.yaml |
| 35 | +│ ├── members/ |
| 36 | +│ │ ├── alice.yaml |
| 37 | +│ │ └── bob.yaml |
| 38 | +│ └── receipts/ |
| 39 | +└── platform-team/ |
| 40 | + ├── team.yaml |
| 41 | + └── members/ |
| 42 | + └── tingting.yaml |
| 43 | +``` |
39 | 44 |
|
40 | | -The presence of `.tfd/` alone does not activate high assurance. Legacy |
41 | | -Workspace v1 is reported as `LEGACY_READ_ONLY` and is never migrated automatically |
42 | | -or written by the v3 state layer. Users needing the legacy control plane can |
43 | | -remain on the frozen v2.1.3 tag. |
| 45 | +`manifest.yaml` indexes team directories. Each `team.yaml` contains the team |
| 46 | +name, purpose, member IDs, and an optional `trace: delivery_receipt` policy. |
| 47 | +Each named member has a `members/<name>.yaml` profile: |
| 48 | + |
| 49 | +```yaml |
| 50 | +display_name: Alice |
| 51 | +responsibility: Implement the agreed product scope |
| 52 | +expected_output: A runnable and verified result |
| 53 | +model: gpt-5.6-sol |
| 54 | +skills: |
| 55 | + - superpowers:test-driven-development |
| 56 | +agency_role: backend-architect |
| 57 | +``` |
44 | 58 |
|
45 | | -## Internal state operations |
| 59 | +`agency_role` is optional one-time provenance. TFD does not install or run |
| 60 | +agency-agents, synchronize personas, or bulk-import roles. |
46 | 61 |
|
47 | | -The optional state CLI has exactly five operations: |
| 62 | +Project setup creates profiles, not Agents. For each requirement, TFD selects |
| 63 | +at most one configured team and its minimum useful member subset. A recurring |
| 64 | +cross-functional composition should be configured as its own team. |
48 | 65 |
|
49 | | -- `inspect` reports absent, valid, blocked, or legacy read-only state. |
50 | | -- `init` creates the approved minimal SQLite database. |
51 | | -- `task-open` creates one approved high-assurance task. |
52 | | -- `task-update` applies one revision-safe update or transition. |
53 | | -- `record-add` appends one typed, non-transition record. |
| 66 | +Before member creation, the configured model must be an exact choice exposed |
| 67 | +by the current `spawn_agent` runtime, and every configured Skill must be |
| 68 | +installed locally under its exact name. Missing dependencies or exact-model |
| 69 | +initialization failures stop formation. TFD does not scan account models, |
| 70 | +install Skills, substitute models, or fall back silently. |
54 | 71 |
|
55 | | -These operations are internal recovery and orchestration support, not five user workflows. |
56 | | -Run them from `plugins/tfd` so Python imports the plugin's `scripts` package: |
| 72 | +See [`plugins/tfd/examples/project-tfd`](plugins/tfd/examples/project-tfd) for |
| 73 | +the complete minimal example. |
57 | 74 |
|
58 | | -```bash |
59 | | -cd plugins/tfd |
60 | | -python3 -m scripts.tfd_state.cli inspect --project-root /path/to/project |
61 | | -``` |
| 75 | +## Delivery receipts |
| 76 | + |
| 77 | +When the selected team sets `trace: delivery_receipt`, TFD writes one short |
| 78 | +Markdown receipt after final delivery. It records only the outcome, selected |
| 79 | +members and contributions, result reference, verification and review result, |
| 80 | +and unresolved items. |
| 81 | + |
| 82 | +A receipt is a human-readable trace, not runtime authority or resumable state. |
| 83 | +TFD keeps no task database, progress log, event stream, receipt index, or |
| 84 | +management CLI. |
62 | 85 |
|
63 | 86 | ## Authority boundary |
64 | 87 |
|
65 | | -TFD workflow approval does not authorize installation, merge, push, tag, release, and external actions. |
66 | | -Each requires separate explicit approval, as do deployment, publishing, |
67 | | -deletion, privileged commands, paid actions, external messages, migration, and |
68 | | -destructive cleanup. |
| 88 | +TFD workflow approval does not authorize installation, merge, push, tag, |
| 89 | +release, deployment, publication, external messages, destructive cleanup, |
| 90 | +privileged commands, paid actions, or scope expansion. Each keeps its normal |
| 91 | +approval boundary. |
69 | 92 |
|
70 | | -The `3.0.0` metadata in this checkout identifies only a local candidate. Do not |
71 | | -infer a tag, marketplace installation, GitHub Release, or deployed artifact |
72 | | -from local tests or preflight output. |
| 93 | +The `3.0.0` metadata identifies only a local candidate. Do not infer a tag, |
| 94 | +installation, GitHub Release, or deployment from local tests. |
73 | 95 |
|
74 | 96 | ## Repository layout |
75 | 97 |
|
76 | 98 | ```text |
77 | | -.agents/plugins/marketplace.json Local candidate marketplace metadata |
78 | 99 | plugins/tfd/.codex-plugin/plugin.json Plugin manifest |
79 | 100 | plugins/tfd/skills/using-tfd/SKILL.md Single user-facing Skill |
80 | | -plugins/tfd/scripts/tfd_state/ Optional SQLite state layer |
81 | | -scripts/check_tfd_budgets.py Hard-budget verifier |
82 | | -scripts/release_preflight.py Local-candidate verifier |
| 101 | +plugins/tfd/examples/project-tfd/ Minimal YAML team example |
| 102 | +scripts/test_plugin_contract.py Package contract |
83 | 103 | ``` |
84 | 104 |
|
85 | 105 | ## Local verification |
86 | 106 |
|
87 | | -Python 3.10 or newer is required. PyYAML is used only by metadata tests; the |
88 | | -runtime state package uses only the Python standard library. |
| 107 | +Python 3.10 or newer and PyYAML are required for tests. |
89 | 108 |
|
90 | 109 | ```bash |
91 | 110 | python3 -m pip install -r requirements.txt |
92 | 111 | python3 -m unittest discover -s scripts -p 'test_*.py' -v |
93 | 112 | cd plugins/tfd |
94 | 113 | python3 -m unittest discover -s scripts -p 'test_*.py' -v |
95 | | -cd ../.. |
96 | | -python3 scripts/check_tfd_budgets.py |
97 | | -python3 scripts/release_preflight.py |
98 | 114 | ``` |
99 | 115 |
|
100 | | -The preflight is local-only. Its successful result is |
101 | | -`{"ok":true,"status":"LOCAL_CANDIDATE","version":"3.0.0"}`; it does not |
102 | | -authorize or perform installation, staging, network access, cachebuster |
103 | | -updates, tagging, pushing, or release work. |
104 | | - |
105 | 116 | ## License |
106 | 117 |
|
107 | 118 | [MIT](LICENSE) |
0 commit comments