Getting Started
Usage
Day-to-day patterns for working with Gem Team.
Start a Task
Describe the outcome you want. The Orchestrator gathers context, classifies complexity, plans, delegates, and verifies.
"Add a rate limiter to the API gateway"
"Find out why the login flow fails on iOS Safari"
"Review the auth module for security issues"
Complexity at a Glance
| Complexity | When | What You See |
|---|---|---|
| TRIVIAL | Typo, rename, or one-shot command | Direct bounded path; otherwise an ephemeral plan |
| LOW | Small, reversible, single-domain work | Ephemeral wave plan |
| MEDIUM | Multiple dependent files, components, or agents | Persistent planner-confirmed plan with risk-adaptive review |
| HIGH | Architecture, API/schema/auth, migration, or risk | Persistent plan with high or critic review and risk checks |
Complex Plans Are Resumable
Every task receives a plan_id. MEDIUM/HIGH work stores a persistent plan.yaml; lower-complexity work uses the ID for correlation only. Discovery is gathered once, then passed to the Planner through bounded planning_context:
docs/plan/{plan_id}/
plan.yaml # Ordered waves, status, and minimal outputs
Task results use minimal role-specific JSON. Detailed evidence stays in task-scoped artifacts; dependent tasks receive only compact, actionable context.
Resume paused work with the exact plan ID:
continue plan 20260714-api-rate-limiter
Continuation and extension require the exact persistent plan ID.
After Successful Work
After final success, Gem Team can promote stable, reusable knowledge when confidence is high. Task-local details stay in workflow state.
- Product decisions ->
docs/PRD.yaml - Technical conventions ->
AGENTS.md - Patterns and gotchas -> Memory (repo, session, or global)
- Repeatable workflows ->
.apm/skills/asSKILL.mdplaybooks, compiled for each target by APM
Practical Tips
- Be specific: include error messages, file paths, and expected behavior.
- Inspect plan artifacts for MEDIUM/HIGH work before execution starts.
- Keep the exact plan ID to correlate, resume, or extend persistent work.
- Ignore
apm_modules/: it is an install cache, not project code.