@agentteams/cli 0.1.22

package/.agentteams/platform/plan-guide.md

@@ -0,0 +1,180 @@
+---
+trigger: model_decision
+description: Reference when creating, executing, or completing a plan.
+---
+# Plan Guide (AgentTeams)
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+This guide defines how to **write** a high-quality plan. For execution details (status transitions, CLI commands, comments), follow your project's workflow conventions and CLI help.
+
+## What a Plan Is
+
+- A plan is a tracked unit of work with a type, status, and priority.
+- Use plans when the work spans multiple steps or requires review and verification.
+- Plans support comments, assignment, and status transitions.
+- Plans have a **type** that classifies the nature of the work:
+  - `FEATURE` — New functionality or capability
+  - `BUG_FIX` — Fix for a defect or unexpected behavior
+  - `ISSUE` — Investigation or issue resolution
+  - `REFACTOR` — Code restructuring without behavior change
+  - `CHORE` — Maintenance, config, docs, or other housekeeping
+
+## Plan Writing Workflow
+
+1. **Clarify requirements** — explore the codebase, interview the requester if needed
+2. **Write plan body** — follow Plan Tiers below to pick the right structure
+3. **Gap analysis** — SHOULD run Metis review; use the self-check below if unavailable
+4. **Register** — `agentteams plan create --file {path} --type {type} --priority {level}`
+
+Repository linkage note:
+
+- If .agentteams/config.json contains `repositoryId`, `plan create` links the new plan to that repository automatically.
+
+## Execution Shortcuts
+
+For standard execution flows, use lifecycle shortcuts instead of manual multi-step status updates.
+
+~~~bash
+# Start plan lifecycle
+agentteams plan start --id {planId}
+
+# Finish plan lifecycle
+agentteams plan finish --id {planId}
+
+# Finish and include completion report with metrics
+agentteams plan finish --id {planId} \
+  --report-title "<what you did and why, in one sentence>" \
+  --report-file .agentteams/cli/temp/{planId-first-8-chars}-report.md \
+  --quality-score <0-100, see Quality Score dimensions> \
+  --report-status <COMPLETED | PARTIAL | FAILED>
+
+~~~
+
+## Plan Start → Execution Flow
+
+When a user explicitly says to start a plan (e.g. "start plan {id}", "let's start {id}"), treat it as an explicit execution approval. Follow this flow:
+
+~~~bash
+# 1. Download runbook
+agentteams plan download --id {planId}
+
+# 2. Check for blocking comments
+agentteams comment list --plan-id {planId}
+
+# 3. Start lifecycle
+agentteams plan start --id {planId}
+~~~
+
+**Decision after comment check:**
+
+| Comments found | Action |
+|---|---|
+| `RISK` or `MODIFICATION` present | Report to user and wait for confirmation before implementing |
+| None (or `GENERAL` only) | Proceed with implementation immediately |
+
+The phrase "start the plan" is an explicit approval signal — do not stop after the CLI status change. Implement unless a blocking comment requires human confirmation.
+
+## Entity Reference Resolution
+
+Plans may contain entity references in `[label](type:id)` or `[label](type:id:path)` format. Resolve them as follows:
+
+1. **ID prefix stripping (IMPORTANT)**: The `id` part may include a type prefix such as `plan_`, `cr_`, `ca_`, `conv_`, or `pm_`. Always strip this prefix before passing the id to any CLI flag (`--id`, `--plan-id`, etc.).
+   - Example: `[My Plan](plan:plan_f62762fc-730a-4201-8586-e2541505ed1b)` → use `f62762fc-730a-4201-8586-e2541505ed1b`
+   - Full prefix list: `plan_` · `cr_` · `ca_` · `conv_` · `pm_`
+2. Resolution by type:
+   - `convention:id:.agentteams/path` → Read the local file at the given path (e.g., `.agentteams/rules/context.md`)
+   - `completionReport:id` → Download with `agentteams report download --id {id}` and read the local file
+   - `postMortem:id` → Download with `agentteams postmortem download --id {id}` and read the local file
+   - `coAction:id` → Download with `agentteams coaction download --id {id}` and read the local file
+
+## During Plan Execution
+
+Post comments to track progress:
+
+- **Risk found**: `agentteams comment create --plan-id {planId} --type RISK --content "<risk description>" --affected-files "<paths>"`
+- **Scope changed**: `agentteams comment create --plan-id {planId} --type MODIFICATION --content "<what changed and why>" --affected-files "<paths>"`
+- **Status update**: `agentteams comment create --plan-id {planId} --type GENERAL --content "<current progress>"`
+
+## After Completing or Cancelling a Plan
+
+Clean up the local runbook:
+
+~~~bash
+agentteams plan cleanup --id {planId}
+~~~
+
+## Plan Tiers — Pick the Right Level
+
+Not every plan needs the same structure. Pick the tier that matches your task size.
+
+### Minimal (1 task, 1–2 files, <30 min)
+
+- `## TL;DR` — 1–2 sentence summary, deliverables
+- `## TODOs` — What to do + Acceptance Criteria per task
+
+### Standard (2–3 tasks, known scope)
+
+Everything in Minimal, plus:
+
+- `## Context` — Original Request / Research Findings
+- `## Work Objectives` — Deliverables / Definition of Done / Must Have / Must NOT Have
+- `## Verification Strategy` — QA tool mapping (API→typecheck+test, CLI→test, Web→build)
+- TODOs add: Must NOT do / References
+
+### Full (4+ tasks, multi-wave, unfamiliar domain)
+
+Everything in Standard, plus:
+
+- Context adds: Interview Summary / Metis Review
+- `## Execution Strategy` — Parallel Waves / Dependency Matrix / Agent Dispatch
+- TODOs add: Agent Profile / Parallelization / QA Scenarios / Commit plan
+
+> When unsure, start with Standard. Upgrade to Full when tasks reach 4+.
+> `plan-template.md` provides a copyable Full-tier template. For Minimal/Standard, extract only the sections you need.
+
+## Task Required Elements
+
+Full tier requires all items. Standard tier requires ★ items only.
+
+- ★ What to do / Must NOT do
+- Recommended Agent Profile (category + skills + reason)
+- Parallelization (Wave / Blocks / Blocked By)
+- ★ References (Pattern / API / External)
+- ★ Acceptance Criteria
+- QA Scenarios (Tool / Steps / Expected Result / Evidence)
+- Commit (message + files + pre-commit)
+
+## Gap Analysis
+
+SHOULD: Ask the Metis agent to review the plan draft before registering.
+
+If Metis is unavailable, self-check:
+
+- [ ] All required sections for the chosen tier present?
+- [ ] Must NOT Have guardrails defined?
+- [ ] Each TODO has acceptance criteria?
+- [ ] Dependency graph correct (no circular blocks)?
+- [ ] File references verified to exist?
+
+## Verification Expectations
+
+- If you touched API code: run API typecheck + tests.
+- If you touched CLI code: run CLI tests.
+- If you introduced a new endpoint: add at least one request-level test.
+- If you changed a template: update its tests to match.
+
+## Common Pitfalls
+
+- Skipping tests because changes "look small"
+- Changing API contracts without updating schemas/tests
+- Writing files to project-specific directories when they should be platform-wide
+- Mixing platform content with project conventions (keep them separate)
+- Excessive comments that restate the code
+- Scope creep beyond task spec
+- Over-abstraction or premature generalization
+- Generic names (data, result, item) that obscure intent
+
+## References
+
+- `plan-template.md` — copyable Full-tier plan template

package/.agentteams/platform/plan-template.md

@@ -0,0 +1,201 @@
+---
+trigger: -
+description: Copyable full plan template. Use as starting point when writing a new plan.
+---
+# Plan Template (Full Tier)
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+> This template is for **Full tier** plans (4+ tasks, multi-wave, unfamiliar domain).
+> For Minimal or Standard plans, refer to the Plan Tiers section in `plan-guide.md` and extract only the sections you need.
+
+## TL;DR
+
+> **Quick Summary**: <!-- 1-2 sentence summary of what this plan achieves -->
+>
+> **Deliverables**:
+>
+> - <!-- file/module 1 — what changes -->
+> - <!-- file/module 2 — what changes -->
+>
+> **Estimated Effort**: <!-- Short / Medium / Long -->
+> **Type**: <!-- FEATURE / BUG_FIX / ISSUE / REFACTOR / CHORE -->
+> **Parallel Execution**: <!-- YES / NO -->
+> **Critical Path**: <!-- Task X → Task Y → ... -->
+
+---
+
+## Context
+
+### Original Request
+
+<!-- What the user/requester asked for and why -->
+
+### Interview Summary
+
+<!-- Key decisions from Q&A with the requester (if applicable) -->
+
+### Research Findings
+
+<!-- What you discovered from exploring the codebase, docs, or external sources -->
+
+### Metis Review
+
+<!-- Gaps identified by Metis review (or self-check results) -->
+
+---
+
+## Work Objectives
+
+### Core Objective
+
+<!-- One sentence: what success looks like -->
+
+### Concrete Deliverables
+
+- <!-- file/module — description -->
+
+### Definition of Done
+
+- <!-- Criterion 1 -->
+- <!-- Criterion 2 -->
+
+### Must Have
+
+- <!-- Non-negotiable requirement -->
+
+### Must NOT Have (Guardrails)
+
+- <!-- Explicitly forbidden action -->
+
+---
+
+## Verification Strategy
+
+> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed.
+
+### QA Policy
+
+- <!-- Tool/command mapping: API→typecheck+test, CLI→test, Web→build+playwright -->
+
+---
+
+## Execution Strategy
+
+### Parallel Execution Waves
+
+~~~
+Wave 1:
+├── Task 1: description [category]
+└── Task 2: description [category]
+
+Wave 2 (Wave 1 complete):
+└── Task 3: description [category]
+~~~
+
+---
+
+## TODOs
+
+---
+
+- 1. Task title
+
+  **What to do**:
+
+  <!-- Detailed steps -->
+
+  **Must NOT do**:
+
+  - <!-- Forbidden action -->
+
+  **Recommended Agent Profile**:
+
+  - **Category**: `<!-- category -->`
+    - Reason: <!-- why this category -->
+  - **Skills**: <!-- skill list or none -->
+
+  **Parallelization**:
+
+  - **Can Run In Parallel**: <!-- YES / NO -->
+  - **Parallel Group**: <!-- Wave N -->
+  - **Blocks**: <!-- Task N or none -->
+  - **Blocked By**: <!-- Task N or none -->
+
+  **References**:
+
+  - <!-- file:lines — description -->
+
+  **Acceptance Criteria**:
+
+  - <!-- Verifiable criterion -->
+
+  **QA Scenarios**:
+
+  ~~~
+  Scenario: description
+    Tool: Bash
+    Steps:
+      1. command
+    Expected Result: what success looks like
+    Failure Indicators: what failure looks like
+    Evidence: .sisyphus/evidence/task-N-name.txt
+  ~~~
+
+  **Commit**: <!-- YES / NO -->
+
+  - Message: `<!-- type(scope): description -->`
+  - Files: <!-- file list -->
+  - Pre-commit: `<!-- verification command -->`
+
+---
+
+## Final Verification Wave
+
+- F1. **Final check** — `quick`
+
+  1. <!-- verification command 1 -->
+  2. <!-- verification command 2 -->
+
+  Output: `<!-- result format -->`
+
+---
+
+## Commit Strategy
+
+- **Task 1**: `<!-- commit message -->`
+- **Task 2**: `<!-- commit message -->`
+
+## Success Criteria
+
+~~~bash
+# <!-- description -->
+<!-- command -->
+# Expected: <!-- result -->
+~~~
+
+---
+
+## QA Scenario Examples
+
+### Good (specific, verifiable)
+
+~~~
+Scenario: API returns 404 for non-existent plan
+  Tool: Bash
+  Steps:
+    1. curl -s -o /dev/null -w "%{http_code}" http://localhost:3001/api/plans/nonexistent-id
+  Expected Result: 404
+  Failure Indicators: 200 or 500
+  Evidence: .sisyphus/evidence/plan-404.txt
+~~~
+
+### Bad (vague, unverifiable)
+
+~~~
+Scenario: API works correctly
+  Tool: Manual
+  Steps:
+    1. Test the API
+  Expected Result: It works
+~~~

package/.agentteams/platform/post-mortem-guide.md

@@ -0,0 +1,92 @@
+---
+trigger: model_decision
+description: Reference when writing a post mortem.
+---
+# Post Mortem Guide (AgentTeams)
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+A post mortem is a written analysis of an incident, focusing on root cause and prevention.
+
+## Goals
+
+- Capture what happened and when
+- Identify the root cause (not symptoms)
+- Document the impact (users, revenue, SLA, operations)
+- Define concrete action items to prevent recurrence
+
+## Before You Start
+
+- Collect logs, alerts, and key timestamps.
+- Identify the affected systems and user segments.
+- Confirm whether this was a one-off or part of a recurring pattern.
+
+## Structure
+
+- Title: short incident identifier
+- Content: narrative of what happened and what was learned
+- Action items: specific tasks with owners and deadlines
+- Status: OPEN, IN_PROGRESS, or RESOLVED
+
+## Root Cause Notes
+
+- Prefer a clear causal chain over vague labels.
+- Distinguish: trigger vs contributing factors vs detection failure.
+- Include "why it was not caught earlier".
+
+## Tips
+
+- Use a clear timeline (timestamps if available)
+- Avoid blame; focus on systems and process
+- Include what detection/monitoring failed and how to improve it
+
+## Action Items
+
+- Make action items concrete and testable.
+- Prefer small items with clear ownership.
+- Track them like normal plans if they require engineering work.
+
+## Post Mortem Content Template
+
+Use this structure for the `--content` field or the `--file` content:
+
+~~~markdown
+## Summary
+<what happened — 1-2 sentences, be specific>
+
+## Timeline
+- HH:MM - <event 1>
+- HH:MM - <event 2>
+
+## Root Cause
+<specific cause, not symptoms — describe the causal chain>
+
+## Impact
+<who/what was affected and for how long>
+
+## What Went Wrong
+- <contributing factor 1>
+- <contributing factor 2>
+
+## What Went Well
+- <what helped limit the damage or speed up recovery>
+~~~
+
+## Post Mortem File Naming
+
+Use `{first 8 characters of planId}-postmortem.md`. Example: if planId is `57a51ec2-cf70-...`, the file name is `57a51ec2-postmortem.md`.
+
+## Useful Commands
+
+~~~bash
+agentteams postmortem create \
+  --plan-id {planId} \
+  --title "<what broke — e.g., 'API 500 on plan finish after schema migration'>" \
+  --file .agentteams/cli/temp/{planId-first-8-chars}-postmortem.md \
+  --action-items "<specific preventive action 1>,<specific preventive action 2>" \
+  --status OPEN
+~~~
+
+Repository linkage note:
+
+- If .agentteams/config.json contains `repositoryId`, `postmortem create` links the postmortem to that repository automatically.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful and considerate
+- Giving and accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior include:
+
+- Harassment, trolling, or insulting comments
+- Public or private abuse of any community member
+- Publishing private information without explicit permission
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and public interactions representing the project.
+
+## Reporting
+
+To report unacceptable behavior, contact maintainers through a private GitHub channel.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1:
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

package/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to AgentTeams CLI
+
+Thanks for your interest in contributing.
+
+This repository is managed as a public mirror of the CLI source-of-truth in the main monorepo.
+
+## Scope
+
+- Issues are welcome for bugs, feature requests, and questions.
+- Pull requests are welcome for docs fixes, typo fixes, and small bug fixes.
+- For major behavior/API changes, open an issue first and align on scope before sending a PR.
+
+## Mirror Policy
+
+- This repository may be updated by automated sync from the source monorepo.
+- Maintainers can close or re-home PRs that conflict with the source-of-truth workflow.
+- If needed, maintainers may re-implement accepted changes in the source monorepo before syncing back.
+
+## Development
+
+- Runtime: Node.js 24+
+- Package manager: npm 10+
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+## Pull Request Checklist
+
+1. Keep scope focused and minimal.
+2. Add or update tests for behavior changes.
+3. Ensure `npm run build` and `npm test` pass.
+4. Describe why the change is needed.
+
+## Code of Conduct
+
+By participating in this project, you agree to follow `CODE_OF_CONDUCT.md`.