Overview¶

English | 日本語

AI Teams is a set of Codex Skills and bounded tools packaged as one Plugin. Its core Skill acts as an accountable product-development lead: it turns a request into a goal and next bet, coordinates only useful specialist work, delivers through the project toolchain, and learns from evidence.

For an explicitly requested or event-triggered cross-project review, AI Teams can run a bounded project-health operation that dispositions every finding and reads completion back from the authoritative tracker. Ordinary status and narrow delivery remain direct; repository age or size never starts an audit.

Start with four concepts¶

Primary concept	What it answers
Goal	What outcome matters?
Bet	What is the next worthwhile attempt?
Work Item	Where is the durable unit of delivery and acceptance?
Evidence	What happened, and what should change next?

These four concepts are enough to begin ordinary work. Terms about integrations, architecture, and delivery mechanics appear only when they affect a decision.

The Plugin does not replace GitHub, Git, CI, code review, security scanners, or planning systems. It selects and interprets those capabilities while preserving their authority and authentication boundaries.

The standard setup is AI Teams + GitHub Plugin + Codex native capabilities. When Linear, Jira, or another planning system is already authoritative, product state remains there and only code delivery is linked to GitHub. Users are not asked to redesign the provider stack for every task.

Linear users can read/search Initiatives, Projects and Issues, propose or apply one change, transition a mapped status, and link delivery work through the Linear planning adapter. Its project profile names the organization/team and field/status mappings; authentication stays with the provider. Changes default to a preview and need separate effect authority to apply. Stale revisions reject, uncertain results require readback, and unavailable Linear never creates a GitHub backlog. Concurrent writers must still serialize edits because Linear has no atomic expected-revision update. Linear backlog recommendations use the live portfolio command below.

Jira Cloud users can use the Jira planning adapter for an existing Project's Epics and Issues: read/search, preview changes, update mapped custom fields, transition an available workflow, link Issues and append comments. The profile binds the tenant/Project and exact field/workflow IDs; unmapped custom fields and rich text are preserved. Changes require separate authority and exact revision/readback checks. An uncertain create or comment must be reconciled before another effect. Confluence pages use a separate read-only adapter bound to the exact space and version; page content is never persisted as planning state. Credentials stay in the integration environment. Project administration and Data Center support remain separate; Jira backlog recommendations use the live portfolio command below.

If the GitHub Plugin is unavailable, unauthorized, or unsupported for an operation, AI Teams can use an explicitly observed standard CLI or registered bundled fallback. If no authorized path exists, it returns a bounded handoff; it never invents success or silently substitutes the system of record.

Repository understanding is likewise optional and provider-neutral. When the pinned Graft CLI companion is available, AI Teams may use one bounded map, context-search, callers/dependencies, blast-radius, or freshness operation. Graft output is retrieval evidence only: exact source, Markdown/JSON contracts, Git, tests, and tracker records remain authoritative. AI Teams works normally with native reads, Git, and rg when Graft is absent or fails. Normal tasks do not install Graft, enable telemetry, configure models or keys, add hooks, or rewrite agent instructions.

Operating model¶

You can opt in to reporting a reviewed, reusable AI Teams defect or improvement to its verified upstream Issue tracker. Reporting is disabled by default and requires an account-owned permission separate from Plugin enablement. The project's own tracker remains authoritative; source trees, transcripts and reflections are not uploaded automatically. Review the complete rendered report locally before transmission. An exact duplicate is reused; other candidates or uncertain results require review without an automatic retry. See upstream reporting and recovery for consent, prerequisites, preview and disabling instructions. This feature does not enable AI Teams in a project or install an update.

A team is coordinated responsibilities and contracts, not necessarily separate agents for each role. One coordinator remains accountable by default; specialist work is added only when independent expertise, context isolation, or parallel work materially improves quality, latency, or evidence. It is not a standing role hierarchy or acceptance evidence.

1. Understand the stakeholder outcome and current evidence.
2. Separate the goal from the requested solution.
3. Identify assumptions, unknowns, constraints, and non-goals.
4. Choose the smallest worthwhile bet.
5. Deliver through the authoritative Work Item and repository workflow.
6. Validate the exact candidate and observe outcome evidence.
7. Stop, iterate, revert, or choose a new bet.

One coordinator is the default. Agent count is never acceptance evidence.

For material work, AI Teams uses Calibrated Delegation before production editing. It first resolves routine choices from explicit intent, accepted preferences, the existing design, established practice, and the simplest reversible default. It asks for direction only when an unresolved choice would materially change product value, public behavior, authority, or an expensive irreversible outcome. Clear, objective, low-risk work such as a narrow bug fix remains direct. A conversational correction that changes the accepted outcome invalidates the prior readiness decision before implementation continues.

Simple outside, rigorous inside¶

Ordinary interactions start with the outcome, the next worthwhile Bet, what happened, and the next supported action. Implementation detail stays available through progressive disclosure instead of becoming onboarding work.

This simplicity never hides safety state. A required approval or action, a failed or pending gate, uncertainty about an external effect, and the absence of an authorized path remain visible when they affect the next decision. The underlying isolation, exact-candidate validation, readback, rollback, and release controls stay rigorous.

When internal terms appear¶

Internal term	Reveal it when the user needs to decide or act
Standard Profile / provider / system of record	Choosing, authenticating, or recovering an integration or authoritative tracker
Control	Opting into persistent discovery, scheduling, queue/recovery state, workers, or a Control UI
Goal Brief / structural reassessment	A costly, ambiguous, or repeated-workaround decision needs deeper framing
Candidate / exact-head validation	A delivery must identify the exact revision and explain a pending or failed merge gate
Authority / approval	An external, privileged, destructive, or otherwise human-owned effect needs consent

The detailed term supplements the Goal, Bet, Work Item, and Evidence path; it does not replace that path or hide a required action, failed gate, or uncertainty.

Persistent settings¶

AI Teams can use reviewed defaults from ~/.codex/ai-teams/settings.json and repository rules from .ai-teams/project-policy.json. Project policy overrides user defaults; an explicit current instruction overrides both. These files may select provider preference order, language and interaction defaults, delivery conventions, and the existing release-policy overlay. They never store credentials, provider availability, absolute project paths, work state, or permission to perform an external effect. Missing files retain product defaults, while malformed or unsafe files are rejected.

When a host supplies learned preferences, they apply below explicit instructions, project policy and user settings, but above product defaults. They use the supported user-preference values and cannot supply project policy or approval. Settings resolution does not retrieve or save memory.

Use ordinary directories for .codex/ai-teams and .ai-teams. A symlink in a settings path is rejected, including a broken directory link with no JSON file. To recover, place the reviewed settings at the canonical location in ordinary directories. A project-root alias still resolves to the same project.

For example, a user settings file may contain:

{"schema": "ai-teams-user-settings/v1", "companion_locale": "ja"}

A project policy may select its documentation language:

{"schema": "ai-teams-project-policy/v1", "documentation_language": "en"}

Live backlog recommendation¶

Run python3 <ai-teams-skill-dir>/scripts/portfolio.py --repo OWNER/REPO to get one recommendation and up to four alternatives from GitHub. No graph JSON is required. GitHub CLI authentication supplies the current account; Issue data and the cursor use the existing disposable cache outside the repo.

The result explains priority, urgency, dependencies, confidence and missing evidence. Low confidence means comparison information is missing, not that implementation succeeded or user impact was measured. Incomplete inventories return no recommendation. Recommendations are for analysis and grant no execution permission; re-read the exact Issue before delivery. Optional Issue comparison fields and the 100-node graph bound are documented in the portfolio contract.

GitHub indexing supports 10,000 open Issues without a count-based stop. Narrow ranking with --goal-ref GOAL, --team TEAM, or --component COMPONENT; team and component use explicit team:VALUE / component:VALUE Issue labels. Each page ranks at most 50 open Issues plus direct dependencies, and returns at most five candidates. truncated and partition.next_cursor show additional pages; repeat the same filters with --cursor CURSOR to inspect them. A page's recommendation is scoped to that page. Stale pages return no recommendation. If synchronization reports partition.resume_required, repeat the finite command to resume its saved provider cursor; it does not run in the background. Only closed history is subject to the 2,000-item retention limit.

For Linear or Jira, reuse your existing adapter profile and explicitly classify its semantic workflow states:

python3 <ai-teams-skill-dir>/scripts/portfolio.py --provider linear \
  --profile linear-project.json --open-state planned --open-state active --closed-state done
python3 <ai-teams-skill-dir>/scripts/portfolio.py --provider jira \
  --profile jira-project.json --open-state planned --open-state active --closed-state done

Use the state names actually configured in your profile; repeat the flags to cover every state exactly once. The original provider description supplies Work Item metadata and optional comparison markers (Jira supports plain ADF paragraphs/code blocks). Dependencies name exact Linear UUIDs or Jira IDs/keys; missing metadata remains visible as unknown. Provider authentication is the same as the planning adapter. Do not pass --repo for an external tracker.

Each finite invocation makes at most 10 provider calls: up to 500 Linear issues or 250 Jira issues including project-scope reads. A pending result means the validated pages were saved; repeat the same command to resume. Only a complete scan replaces the accepted index and reconciles deletions or lost access.

Use --goal-ref, --team or --component to select a bounded partition and --cursor with the returned partition cursor to continue it. Goal references come from explicit metadata; team:/component: labels provide facets, and Linear defaults its team facet to the native team ID. Unknown or out-of-partition dependencies prevent a delivery recommendation. Ranking includes at most 100 open/direct-dependency nodes and five candidates; stale/truncated scope is shown.

The disposable cache now stores normalized native records, including descriptions, but no credentials. The old fingerprint-only cache must be explicitly removed and rebuilt if cache_conflict is returned. Rebuild also after changed profile or a scan's 24-hour expiry. Failed reads or commits preserve accepted inventory and its watermark; GitHub is never selected as a fallback. See the external portfolio contract.

Evidence that arrives during later work¶

An Issue can opt into a deferred acceptance check when its remaining evidence will naturally appear during another delivery. For example, a build-path fix can wait for an unrelated push with no Pages check and a documentation push with a successful build. AI Teams checks a bounded set of registrations at completed check observation and returns authorized evidence to the original Issue. Partial evidence keeps that Issue open; all effective requirements and normal completion gates still apply.

Registrations live in the original Issue and can expire or be cancelled. Version 1 supports exact GitHub commit paths and app/name check identities, with a declared observation window for absence. It executes no arbitrary hook code and adds no background polling. Activity outside AI Teams may require an explicit project-health reconciliation. Evidence-write permission is separate from permission to change acceptance or close an Issue.

See the deferred acceptance contract for the registration and bounded input format.

Progress and decisions in one place¶

Ask AI Teams “Show progress and the decisions that need my answer.” For a GitHub project it reads current Goals, Bets, observations and pending decisions, with the recommendation, consequence, and work that waits or continues. Issues without explicit Goal/Bet links remain visible as unlinked work; AI Teams does not infer those relationships or treat an empty Decision Inbox as an empty backlog. No configured job source means job status is unavailable.

The installed command is:

python3 <ai-teams-skill-dir>/scripts/decision_inbox.py --repo OWNER/REPO status

Use decisions, goals, bets, evidence, or jobs instead of status for a focused view. --jobs-database <existing-Control-Lite-store> is optional and read-only. To answer, tell AI Teams which decision and option you selected. It refreshes the exact decision, checks the displayed revision and records the response only under your existing authority. The CLI proposes an answer first:

python3 <ai-teams-skill-dir>/scripts/decision_inbox.py --repo OWNER/REPO answer \
  --issue NUMBER --revision 'EXACT-DISPLAYED-REVISION' \
  --answer 'OFFERED-OPTION' --rationale 'Reason for this selection'

An authorized agent may add --apply --authority-basis <exact-authority-reference> to persist that response. withdraw and expire use the same identity and rationale without an answer. An outdated response requires a refreshed decision; it is never silently reapplied. Responses do not authorize deployment or resume jobs. Legacy decisions with missing scope are shown as requiring explicit migration before these Inbox actions. The Decision Inbox contract describes schemas, provider limits and recovery.

Follow one Goal across repositories¶

An explicitly owner-approved Project Workspace can link a Goal and optional Bet to Work Items, pull requests and deployments in up to 20 exact repositories. The Workspace records provider revisions and an exact allowlist; it does not create another backlog. Reads inside that selected scope need no repeated repository confirmation. Writes still require authority for the exact effect.

Use the installed Skill's scripts/project_state.py workspace-check before a scoped provider operation, and workspace-status to combine complete supplied repository snapshots. Both take bounded JSON on stdin and perform zero provider operations themselves. The host/provider supplies authenticated observations; this entry point does not automatically fetch repositories or deploy anything. Missing repositories or stale expected revisions reject; stale observation health remains visible. Dependencies and deployment order are advisory, and merged PRs or successful deployments do not prove the Bet's outcome.

The Workspace contract defines the input fields, exact identity rules, limits and reconstruction path. Existing single-repository commands remain supported without migration.