@agentteams/cli 0.1.22

package/.agentteams/config.json

@@ -0,0 +1,8 @@
+{
+  "teamId": "1939e8e3-706b-48f1-9dab-ff1b5399f804",
+  "projectId": "b2949695-3284-4d19-b9a4-4d2a9e905fde",
+  "agentName": "cli-agent",
+  "apiKey": "key_eaf85b02-c8a2-40ec-98bf-ba9983c790ff_bdb34ca3-c68c-4265-b68b-a9d9394cbd42",
+  "apiUrl": "https://api.agentteams.run",
+  "repositoryId": "f9db0ce9-be0d-4938-91d9-98b903413260"
+}

package/.agentteams/convention.md

@@ -0,0 +1,100 @@
+---
+trigger: always_on
+description: -
+agentInstruction: |
+  Always reference the items below.
+  - (no always_on items)
+---
+
+# AgentTeams Convention
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+## Entity References & ID Handling
+
+User messages from the AgentTeams web UI may contain entity references in `[label](type:id)` or `[label](type:id:path)` format.
+
+- **ID prefix stripping (IMPORTANT)**: The `id` part includes a type prefix (`plan_`, `cr_`, `ca_`, `conv_`, `pm_`). Always strip this prefix before passing the id to any CLI flag (`--id`, `--plan-id`, etc.).
+  - Example: `[Safari pull-to-refresh](plan:plan_f62762fc-730a-4201-8586-e2541505ed1b)` → use `f62762fc-730a-4201-8586-e2541505ed1b`
+  - Full prefix list: `plan_` · `cr_` · `ca_` · `conv_` · `pm_`
+- 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
+
+---
+
+> ⚠️ When creating, updating, or deleting platform documents (plans, conventions, reports, postmortems, co-actions), do not stop at writing local files — always register the result to the server via the CLI.
+
+Report status to AgentTeams **if you are working under a plan**.
+
+> If the CLI is unavailable, skip reporting and continue the task.
+
+## Plan Lifecycle (Quick Reference)
+
+```bash
+# Start
+agentteams plan start --id {planId}
+
+# Finish (with completion report)
+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> \
+  --report-status <COMPLETED | PARTIAL | FAILED>
+```
+
+For report file structure, quality score dimensions, and status rules, see `.agentteams/platform/completion-report-guide.md`.
+
+## Completion Report Without a Plan
+
+1. Ask the user: "No active plan found. Should I create a quick plan to record this work?"
+2. If approved:
+   ```bash
+   agentteams plan quick --title "<brief work summary>" \
+     --content "<TL;DR and actual tasks performed>" \
+     --type <FEATURE | BUG_FIX | ISSUE | REFACTOR | CHORE>
+   ```
+   Then follow the report creation steps in `.agentteams/platform/completion-report-guide.md`.
+3. If declined, create a standalone report (no plan link). See `.agentteams/platform/completion-report-guide.md`.
+
+---
+
+## Plan Workflow Rules
+
+### Before starting work on a plan
+
+1. Download the plan as a local runbook:
+   ```bash
+   agentteams plan download --id {planId}
+   ```
+   This saves to `.agentteams/cli/active-plan/{filename}.md`. Read this file at the start of your work.
+
+2. Check for comments (especially `RISK` comments):
+   ```bash
+   agentteams comment list --plan-id {planId}
+   ```
+
+3. For detailed execution workflow (entity references, comments, cleanup), see `.agentteams/platform/plan-guide.md`.
+
+### Guide checks before writing documents
+
+Before writing or updating **platform documents** (plans, reports, conventions, postmortems), read the matching guide:
+
+| Document type | Guide to read |
+|---|---|
+| Plan execution | `.agentteams/platform/plan-guide.md` |
+| New plan | `.agentteams/platform/plan-template.md` |
+| Completion report | `.agentteams/platform/completion-report-guide.md` |
+| Postmortem | `.agentteams/platform/post-mortem-guide.md` |
+| Convention (create) | `.agentteams/platform/convention-authoring-guide.md` |
+| Convention (update/delete) | `.agentteams/platform/convention-ud-guide.md` |
+| Co-action (handoff) | `.agentteams/platform/co-action-guide.md` |
+
+
+---
+
+## Project Convention Index
+
+No project conventions found. Use the web dashboard to create conventions.

package/.agentteams/platform/co-action-guide.md

@@ -0,0 +1,144 @@
+---
+trigger: model_decision
+description: Reference when creating a co-action (handoff document).
+---
+# Co-Action Guide (AgentTeams)
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+A co-action is a **handoff document** — it captures knowledge that cannot be inferred from code alone. Use it to transfer implicit knowledge between agents or between sessions.
+
+## What a Co-Action Is
+
+- A co-action records **discoveries, decisions, and context** accumulated during a work session.
+- It is NOT a session context dump. Only include information that has lasting value for the next reader.
+- Co-actions link to related plans, completion reports, and post-mortems for full traceability.
+- Takeaways track the key insights and lessons learned from the work.
+
+## When to Create a Co-Action
+
+- After completing a multi-session or multi-agent project
+- When handing off work to another agent or team member
+- When a body of implicit knowledge would be lost without documentation
+- Before a long pause in active development on a feature
+
+## Content Structure
+
+Write the co-action content with these sections. Include only sections that have meaningful content — skip empty ones.
+
+~~~markdown
+## Key Discoveries
+- <findings that are not obvious from the code>
+- <workarounds, undocumented behaviors, environment quirks>
+
+## Design Decisions
+- <decision>: <rationale — why this approach, what alternatives were rejected>
+
+## Usage Scenarios
+- <how the feature/system is intended to be used>
+- <edge cases or non-obvious interaction patterns>
+
+## Non-Goals
+- <what was intentionally excluded and why>
+
+## Risks / Trade-offs
+- <known compromises and their potential impact>
+- <technical debt introduced and conditions for revisiting>
+
+## Follow-up / Known Constraints
+- <what the next agent should continue or address>
+- <temporary workarounds that need permanent solutions>
+- <incomplete items with context on where they left off>
+~~~
+
+## Section Writing Tips
+
+### Key Discoveries
+Focus on things the next reader cannot find by reading code. Examples: "Prisma 7 delegate requires wrapper pattern due to type inference bug", "Docker build caches COPY layer even when file content changes if mtime is unchanged".
+
+### Design Decisions
+State the decision and the reason. Bad: "Used Redis". Good: "Chose Redis over in-memory cache because the service runs multi-instance and cache must be shared; accepted the ops overhead."
+
+### Non-Goals
+Prevent scope creep by the next agent. Be explicit about what was considered and deliberately excluded.
+
+### Follow-up / Known Constraints
+This is the most critical section for handoff. Be specific enough that the next agent can resume without re-investigating.
+
+## Visibility
+
+- `PRIVATE` (default): only the creator can view/access
+- `PROJECT`: all project members can view; only the creator can change status, visibility, or delete
+
+## Takeaways
+
+Takeaways capture **key insights** that emerged during the work — things the next agent should know but might not discover on their own.
+
+Use takeaways when:
+- You discovered a non-obvious constraint or behavior (e.g., "Fastify response schema silently strips undefined fields")
+- A design decision was made that isn't documented elsewhere
+- You found a workaround that future agents should reuse (or avoid)
+- The task revealed risks or follow-up items that don't belong in the main content
+
+Takeaways are separate from content. Content is the structured handoff document; takeaways are concise, standalone insights attached to it.
+
+~~~bash
+agentteams coaction takeaway-create --id {coActionId} --content "<insight>"
+~~~
+
+## Useful Commands
+
+~~~bash
+# Create
+agentteams coaction create \
+  --title "<concise handoff title>" \
+  --file .agentteams/cli/temp/{descriptive-name}-coaction.md \
+  --visibility PRIVATE
+
+# Download for reference
+agentteams coaction download --id {coActionId}
+
+# Link related entities
+agentteams coaction link-plan --id {coActionId} --plan-id {planId}
+agentteams coaction link-completion-report --id {coActionId} --completion-report-id {crId}
+agentteams coaction link-post-mortem --id {coActionId} --post-mortem-id {pmId}
+
+# Takeaways
+agentteams coaction takeaway-create --id {coActionId} --content "<insight>"
+agentteams coaction takeaway-list --id {coActionId}
+agentteams coaction takeaway-update --id {coActionId} --takeaway-id {takeawayId} --content "<updated insight>"
+agentteams coaction takeaway-delete --id {coActionId} --takeaway-id {takeawayId}
+# Update content
+agentteams coaction update --id {coActionId} --file .agentteams/cli/temp/{name}-coaction.md
+
+# Change status
+agentteams coaction update --id {coActionId} --status CLOSED
+~~~
+
+## Output Behavior
+
+- `coaction create` and `coaction update` print post-action tips to **stderr**.
+- Structured command results (for `--format json`) remain on **stdout**.
+- This separation prevents JSON pipeline parsing failures when tips are shown.
+
+~~~bash
+# Keep stdout clean for JSON consumers
+agentteams coaction create \
+  --title "<title>" \
+  --file .agentteams/cli/temp/{name}-coaction.md \
+  --format json \
+  2>/tmp/coaction-tips.log
+~~~
+
+## Common Pitfalls
+
+- Dumping raw session logs instead of curated knowledge
+- Writing implementation details that belong in a completion report
+- Skipping the "Follow-up / Known Constraints" section — this is the most valuable part for handoff
+- Forgetting to link related plans and reports
+- Using PRIVATE visibility when the knowledge should be shared with the team
+- Assuming info tips are printed to stdout; they are intentionally sent to stderr
+
+## References
+
+- Related guides: `plan-guide.md`, `completion-report-guide.md`, `post-mortem-guide.md`

package/.agentteams/platform/completion-report-guide.md

@@ -0,0 +1,146 @@
+---
+trigger: model_decision
+description: Reference when creating a completion report.
+---
+# Completion Report Guide (AgentTeams)
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+Completion reports capture what changed, why it changed, how it was verified, and what remains.
+
+## When to Create a Report
+
+- After finishing a plan
+- After shipping a user-visible change
+- After completing a risky refactor or bug fix
+
+## What Makes a Good Report
+
+- Specific: names the feature/bug and the reason it mattered
+- Verifiable: includes the commands you ran (and results)
+- Scoped: states what was intentionally NOT changed
+- Actionable: calls out follow-ups if any remain
+
+## What to Include
+
+- Purpose: why this work was needed
+- Scope: what areas/modules were touched
+- Verification: exact commands you ran and whether they passed
+- Risks: potential side effects or follow-up work
+
+## Contract Note
+
+- `report create` and completion report payloads do **not** use `reportType` anymore.
+- Use `status` + metrics (commit and line/file stats) to describe report context.
+
+## Report File Structure
+
+Write the report file with this structure:
+
+~~~markdown
+## Summary
+- <what changed and why — be specific, not generic>
+
+## Verification
+- typecheck: <pass or fail, with the command you ran>
+- tests: <pass or fail, with the command you ran>
+
+## Notes
+- <risks, follow-ups, or "none">
+
+## Conventions Referenced
+- <list .agentteams/rules/*.md files you actually referenced — do not guess>
+~~~
+
+## Report File Naming
+
+Use `{first 8 characters of planId}-report.md`. Example: if planId is `57a51ec2-cf70-...`, the file name is `57a51ec2-report.md`.
+
+For standalone reports (no plan), use a descriptive name: `<feature-or-fix-name>-report.md`.
+
+> ⚠️ **Use either Path A or Path B, not both.** Running both simultaneously will create duplicate completion reports for the same plan.
+>
+## Plan-Linked vs Non-Plan Reports
+
+You can attach report content directly while finishing a plan:
+
+~~~bash
+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 section> \
+  --report-status <COMPLETED | PARTIAL | FAILED>
+
+~~~
+
+> Git metrics (`commitHash`, `branchName`, `filesModified`, `linesAdded`, `linesDeleted`) are auto-collected. Use `--no-git` to disable. Manual overrides: `--duration-seconds`, `--commit-start`, `--commit-end`, `--pull-request-id`.
+
+If you were working under a plan, link the report to the plan:
+
+~~~bash
+agentteams report create \
+  --plan-id {planId} \
+  --title "<what you did and why, in one sentence>" \
+  --file .agentteams/cli/temp/{planId-first-8-chars}-report.md \
+  --quality-score <0-100> \
+  --status <COMPLETED | PARTIAL | FAILED>
+~~~
+
+If you were not working under a plan, omit the plan id:
+
+~~~bash
+agentteams report create \
+  --title "<what you did and why, in one sentence>" \
+  --file .agentteams/cli/temp/<feature-or-fix-name>-report.md \
+  --quality-score <0-100> \
+  --status <COMPLETED | PARTIAL | FAILED>
+~~~
+
+Repository linkage note:
+
+- If .agentteams/config.json contains `repositoryId`, `report create` links the report to that repository automatically.
+
+## Metrics (Auto + Manual)
+
+`report create` and `plan finish` can attach work metrics for insight workflows.
+
+- Auto-collected by default (git context required):
+  - `commitHash`, `branchName`, `filesModified`, `linesAdded`, `linesDeleted`
+- Manual-only fields:
+  - `durationSeconds`, `commitStart`, `commitEnd`, `pullRequestId`
+- `--no-git` disables auto collection.
+- Manual options override auto-collected values.
+
+## Quality Score
+
+Work quality is self-assessed by the agent on a 0-100 scale. Use the four dimensions below to judge holistically.
+
+| Dimension | What to check |
+|---|---|
+| Verification | Did typecheck and tests pass? |
+| Completeness | Were all requirements addressed? |
+| Scope Adherence | Were changes limited to the requested scope? Were conventions followed? |
+| Side Effects | Did the change avoid unintended impact on existing behavior? |
+
+| Score | Meaning |
+|---|---|
+| 90-100 | All verification passed. All requirements met. Conventions followed. No side effects. |
+| 70-89 | Minor gaps: verification partially skipped, slight scope overage, or minor convention deviations. |
+| 0-69 | Verification failed, requirements unmet, significant scope violation, or side effects introduced. |
+
+> Convention violations (naming, logging, PR rules, etc.) count against Scope Adherence.
+> A score of 90+ requires conventions to be followed.
+
+## Verification Examples
+
+~~~bash
+cd api && npm run typecheck
+cd api && npm test
+cd cli && npm test
+~~~
+
+## Notes
+
+- Keep reports factual and reproducible.
+- Prefer describing *why* over listing every line-level change.
+- If verification was skipped, state the reason explicitly.

package/.agentteams/platform/convention-authoring-guide.md

@@ -0,0 +1,112 @@
+---
+trigger: -
+description: Reference when writing or editing project convention markdown files.
+---
+# Convention Authoring Rules (AgentTeams)
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+This guide defines the baseline rules for authoring and editing convention files under `.agentteams/<category>/*.md`.
+For the convention body, follow the structures and elements supported by the **Web Convention Editor toolbar** so the content stays consistent across Web/CLI/AI workflows.
+
+## 1) File structure
+
+- A convention file consists of **Frontmatter (optional)** + **Markdown body**.
+- Frontmatter uses YAML and must be placed at the very top of the file.
+
+Example:
+
+~~~markdown
+---
+trigger: always_on
+description: "..."
+agentInstruction: |
+  ...
+---
+
+# Title
+
+- Item
+~~~
+
+## 2) Recommended frontmatter fields
+
+- `trigger` (optional): a hint for auto-apply/reference triggers (e.g. `always_on`, `model_decision`, `-`)
+- `description` (optional): a short summary of purpose/scope
+- `agentInstruction` (optional): explicit instructions for agents (multi-line supported)
+
+Notes:
+
+- Frontmatter may be generated/normalized by the server, and some fields may be ignored or overwritten during updates.
+
+## 3) Category / path rules
+
+- Use one of the following values for `<category>`:
+  - `rules`, `skills`, `guides`, `references`
+- Use the path format `.agentteams/<category>/<fileName>.md`.
+- Prefer lowercase, hyphen-based file names (e.g. `api-routes.md`).
+- Avoid file name collisions within the same category; depending on policy, the server/CLI may reject conflicts.
+
+## 4) Body authoring rules (Web editor toolbar baseline)
+
+### Structure (Headings)
+
+- **H1**: top-level rule section title
+- **H2**: major subsections under H1
+- **H3**: detailed rules under H2
+- **H4**: only when further subdividing H3
+- **Horizontal rule (HR)**: separate unrelated sections/topics
+
+> Do **not** skip heading levels (e.g. H1 → H3 is not allowed).
+
+### Blocks
+
+- **Blockquote**: warnings/constraints that must stand out
+- **Bullet list**: list rules by items
+- **Ordered list**: step-by-step procedures
+- **Task list**: execution/verification checklist
+- **Table**: summarize options/values/exceptions
+- **Code block**: runnable examples or command snippets (use language tags when possible)
+
+### Inline
+
+- **Bold**: emphasize key conclusions/keywords
+- **Italic**: optional supplemental notes
+- **Inline code**: literal strings such as identifiers, file paths, commands
+- **Links**: connect to related references (use descriptive link text)
+
+### Writing style
+
+- Prefer **imperative** phrasing for rules (e.g. "Do X", "Do not do Y").
+- Wrap examples in fenced code blocks and keep them executable when possible.
+- Prefer multiple smaller, focused conventions over one huge document.
+
+### Markers (recommended prefixes)
+
+Use these prefixes consistently across documents (include a trailing space after the emoji):
+
+- `✅ `: correct example
+- `❌ `: incorrect example
+- `🚫 `: strictly forbidden (including policy/security violations)
+- `⚠️ `: warning/caution
+- `📌 `: key summary
+- `💡 `: tip/reference
+- `🎯 `: goal/intent
+
+## 5) Useful Commands
+
+~~~bash
+# Create a new convention
+agentteams convention create --file .agentteams/{category}/{convention-name}.md
+
+# Download all conventions (required before update/delete)
+agentteams convention download
+
+# Preview update (dry-run)
+agentteams convention update --file .agentteams/{category}/{convention-name}.md
+
+# Apply update to server
+agentteams convention update --file .agentteams/{category}/{convention-name}.md --apply
+~~~
+
+> Place the file under `.agentteams/<category>/` before running `convention create`. The `<category>` must be one of: `rules`, `skills`, `guides`, `references`.

package/.agentteams/platform/convention-ud-guide.md

@@ -0,0 +1,59 @@
+---
+trigger: -
+description: Reference when updating or deleting project conventions via the CLI.
+---
+# Convention Update/Delete Guide (AgentTeams)
+
+> ⚠️ This file is automatically deployed from the server. Do not edit it directly.
+
+This guide explains how to update or delete **project convention files** using the `agentteams` CLI.
+
+## Preconditions
+
+- Update/delete only works for files produced by:
+
+~~~bash
+agentteams convention download
+~~~
+
+- Uploading arbitrary local files is not supported.
+
+## Recommended workflow
+
+1) Download conventions (also creates a local manifest used for mapping)
+
+~~~bash
+agentteams convention download
+~~~
+
+2) Edit the downloaded markdown files under `.agentteams/<category>/*.md`
+
+3) Preview changes (default: dry-run)
+
+~~~bash
+agentteams convention update --file .agentteams/rules/core-rules.md
+~~~
+
+- This prints a diff and does **not** update the server.
+
+4) Apply the update to the server
+
+~~~bash
+agentteams convention update --file .agentteams/rules/core-rules.md --apply
+~~~
+
+## Concurrency/conflict handling
+
+- The CLI prints a local diff first (dry-run by default).
+- When applying an update, the CLI sends the server's `updatedAt` value along with the request.
+- The server is authoritative and rejects the update on conflict (HTTP 409). The default policy is to stop safely.
+
+## Delete
+
+~~~bash
+# dry-run (default)
+agentteams convention delete --file .agentteams/rules/core-rules.md
+
+# apply
+agentteams convention delete --file .agentteams/rules/core-rules.md --apply
+~~~