Production Best Practices

Project-Scoped Installs

Prefer project-scoped installs for teams. apm.yml and apm.lock.yaml make setup reproducible across environments and CI.

Version Pinning

apm install 'mubaidr/gem-team#gem-team-v<version>' --target copilot

Release tags use gem-team-v<version>. Pin a published tag from GitHub Releases and commit the lockfile.

Updates and Lockfiles

apm install restores the versions recorded in apm.lock.yaml. Update deliberately:

apm update mubaidr/gem-team --yes
apm update -g mubaidr/gem-team --yes

The first command updates a project installation; the second updates ~/.apm/. Use apm self-update --check to check the APM CLI without updating it.

Housekeeping

Keep apm_modules/ out of Git by adding it to .gitignore.
Run apm run check before releases and in CI.
Review generated files before committing large updates.

Approval-Gated Operations

Require explicit approval before execution:

Production deployment
Infrastructure provisioning
Data migration
Destructive operations

Knowledge vs. Workflow State

Purpose	Location
Stable project rules and conventions	`AGENTS.md`
Persistent MEDIUM/HIGH workflow state	`docs/plan/{plan_id}/plan.yaml`
Ephemeral TRIVIAL/LOW workflow state	In memory, correlated by `plan_id`

Agent results are minimal and role-specific. Keep status, failure classification, needed evidence, and actionable downstream handoffs. Do not add a universal learn or per-criterion acceptance-results field. Store detailed logs and reports in task-scoped artifacts and return a path or manifest when needed. Ephemeral workflows must not read or write persistent plan artifacts.

Contributing

How to contribute to Gem Team.

Local Development

Build and develop Gem Team from source.