trackops 2.0.3 → 2.0.5

package/skills/trackops/locales/en/SKILL.md

@@ -1,122 +1,126 @@
----
-name: "trackops"
-description: "Global TrackOps skill for explaining what TrackOps does, requiring explicit npm runtime installation, and guiding local project and OPERA activation inside each repository."
----
-
-# TrackOps
-
-Use this localized file when the conversation and project should run in English.
-
-TrackOps is for working with agents on real projects without mixing the product itself with the operational layer.
-
-Use this skill when someone:
-
-- wants to start a project with AI agents
-- already has a repository and needs operational structure
-- needs to activate TrackOps and, if needed, OPERA
-- wants the same workflow in English or Spanish
-
-## What this skill does
-
-This skill:
-
-- explains what TrackOps is and when to use it
-- requires an explicit and visible runtime installation
-- guides per-repository activation
-- helps route OPERA into either `direct bootstrap` or `agent handoff`
-
-## What this skill does not do
-
-This skill does not:
-
-- install packages by itself
-- execute remote code silently
-- modify a repository before the runtime exists
-- replace the `trackops` runtime
-
-## Quick flow
-
-Install the marketplace skill with:
-
-```bash
-npx skills add Baxahaun/trackops
-```
-
-Then confirm that the `trackops` runtime exists. If it is missing, ask the user to install it explicitly:
-
-```bash
-npm install -g trackops
-trackops --version
-```
-
-Rules:
-
-- the skill must not install packages or execute remote code by itself
-- the runtime is installed through a visible and auditable npm step
-- the skill may verify `trackops --version`, but it must not chain silent installs
-- the skill must not create repository files by itself
-
-## Project activation
-
-Inside the repository:
-
-```bash
-trackops init
-trackops opera install
-```
-
-Core rules:
-
-- treat the global skill as an instruction layer
-- treat runtime installation as explicit and separate
-- use `ops/contract/operating-contract.json` as the machine contract when it exists
-- use `ops/project_control.json` as the operational source of truth
-- use `ops/policy/autonomy.json` before approval-sensitive actions
-- use `/.env` and `/.env.example` as the environment contract
-- keep generated operational docs under `ops/`
-- use `trackops locale get|set` and `trackops doctor locale` when language matters
-
-## How OPERA enters the flow
-
-OPERA no longer assumes every user is technical.
-
-TrackOps classifies:
-
-- user technical level
-- current project state
-- available documentation
-
-Then it chooses one of two routes:
-
-- `direct bootstrap`
-  for technical users and already-defined repositories
-- `agent handoff`
-  for early ideas, non-technical users, or weak documentation
-
-If TrackOps routes bootstrap to the agent:
-
-- read `ops/bootstrap/agent-handoff.md`
-- or print it with `trackops opera handoff --print`
-- require these outputs:
-  - `ops/bootstrap/intake.json`
-  - `ops/bootstrap/spec-dossier.md`
-  - `ops/bootstrap/open-questions.md` when important gaps remain
-- resume with:
-
-```bash
-trackops opera bootstrap --resume
-```
-
-## What someone arriving from skills.sh should understand
-
-- the global skill installs instructions into the agent
-- the runtime is installed separately with npm
-- `trackops init` activates the project
-- `trackops opera install` adds the full operating framework only when needed
-- TrackOps separates product and operations so the repository stays manageable
-
-## Which reference to read and when
-
-- read `locales/en/references/activation.md` only for installation, runtime verification, locale bootstrap, and repository activation
-- read `locales/en/references/workflow.md` only when TrackOps is already active and you need day-to-day repository operations
-- read `locales/en/references/troubleshooting.md` only when explicit installation, `trackops` detection, resume, or environment contract handling fails
+---
+name: "trackops"
+description: "Global TrackOps skill for explaining what TrackOps does, requiring explicit npm runtime installation, and guiding local project and OPERA activation inside each repository."
+---
+
+# TrackOps
+
+Use this localized file when the conversation and project should run in English.
+
+TrackOps is a local control and coordination system for AI-agent software development.
+
+This skill is the entry point to the system. Use it when someone:
+
+- wants to start a project with AI agents
+- already has a repository and needs operational structure
+- needs to activate TrackOps and, if needed, OPERA
+- wants the same workflow in English or Spanish
+
+## What this skill does
+
+This skill:
+
+- explains what TrackOps is and when to use it
+- requires an explicit and visible runtime installation
+- guides per-repository activation
+- helps route OPERA into either `direct bootstrap` or `agent handoff`
+- explains that installing OPERA activates a team of agents coordinated by `opera-skill`
+
+## What this skill does not do
+
+This skill does not:
+
+- install packages by itself
+- execute remote code silently
+- modify a repository before the runtime exists
+- replace the `trackops` runtime
+
+## Quick flow
+
+Install the marketplace skill with:
+
+```bash
+npx skills add Baxahaun/trackops
+```
+
+Then confirm that the `trackops` runtime exists. If it is missing, ask the user to install it explicitly:
+
+```bash
+npm install -g trackops
+trackops --version
+```
+
+Rules:
+
+- the skill must not install packages or execute remote code by itself
+- the runtime is installed through a visible and auditable npm step
+- the skill may verify `trackops --version`, but it must not chain silent installs
+- the skill must not create repository files by itself
+
+## Project activation
+
+Inside the repository:
+
+```bash
+trackops init
+trackops opera install
+```
+
+Core rules:
+
+- treat the global skill as an instruction layer
+- treat runtime installation as explicit and separate
+- use `ops/contract/operating-contract.json` as the machine contract when it exists
+- use `ops/project_control.json` as the operational source of truth
+- use `ops/policy/autonomy.json` before approval-sensitive actions
+- use `/.env` and `/.env.example` as the environment contract
+- keep generated operational docs under `ops/`
+- use `trackops locale get|set` and `trackops doctor locale` when language matters
+
+## How OPERA enters the flow
+
+OPERA no longer assumes every user is technical.
+
+TrackOps classifies:
+
+- user technical level
+- current project state
+- available documentation
+
+Then it chooses one of two routes:
+
+- `direct bootstrap`
+  for technical users and already-defined repositories
+- `agent handoff`
+  for early ideas, non-technical users, or weak documentation
+
+Once active, OPERA automatically installs a team of specialized agents under `ops/.agents/skills/`. The coordinator (`opera-skill`) decides which phase the project is in, which agent should act, when to delegate, and when to block progress.
+
+If TrackOps routes bootstrap to the agent:
+
+- read `ops/bootstrap/agent-handoff.md`
+- or print it with `trackops opera handoff --print`
+- require these outputs:
+  - `ops/bootstrap/intake.json`
+  - `ops/bootstrap/spec-dossier.md`
+  - `ops/bootstrap/open-questions.md` when important gaps remain
+- resume with:
+
+```bash
+trackops opera bootstrap --resume
+```
+
+## What someone arriving from skills.sh should understand
+
+- the global skill installs instructions into the agent
+- the runtime is installed separately with npm
+- `trackops init` activates the project
+- `trackops opera install` adds the full operating framework only when needed
+- TrackOps separates product and operations so the repository stays manageable
+
+## Which reference to read and when
+
+- read `locales/en/references/activation.md` only for installation, runtime verification, locale bootstrap, and repository activation
+- read `locales/en/references/workflow.md` only when TrackOps is already active and you need day-to-day repository operations
+- read `locales/en/references/troubleshooting.md` only when explicit installation, `trackops` detection, resume, or environment contract handling fails
+- `opera-skill` is a project skill, not a reference of this global skill. It is installed with OPERA and coordinates work inside the repository.

package/skills/trackops/locales/en/references/activation.md

@@ -1,75 +1,94 @@
-# Activation
-
-## Global install
-
-```bash
-npx skills add Baxahaun/trackops
-npm install -g trackops
-trackops --version
-```
-
-The global skill installs instructions for the agent.
-
-The `trackops` runtime is installed separately through npm so the step stays visible, auditable, and easy to verify.
-
-Before continuing:
-
-- confirm that `trackops --version` returns a valid version
-- if it does not, fix PATH or reinstall `trackops`
-- the skill must not try to install the runtime by itself
-
-## Local activation
-
-Inside a repository:
-
-```bash
-trackops init
-trackops opera install
-```
-
-By default, `trackops init` creates a split workspace with:
-
-- `app/`
-- `ops/`
-- `/.env`
-- `/.env.example`
-- `.trackops-workspace.json`
-
-## OPERA routing
-
-OPERA always starts by classifying:
-
-- technical level
-- project state
-- documentation state
-
-If the project is still early or the user is non-technical, TrackOps writes:
-
-- `ops/bootstrap/agent-handoff.md`
-- `ops/bootstrap/agent-handoff.json`
-
-The agent must produce:
-
-- `ops/bootstrap/intake.json`
-- `ops/bootstrap/spec-dossier.md`
-- `ops/bootstrap/open-questions.md` when needed
-
-When the quality gate passes, OPERA compiles:
-
-- `ops/contract/operating-contract.json`
-- `ops/genesis.md`
-- `ops/policy/autonomy.json`
-
-Resume with:
-
-```bash
-trackops opera bootstrap --resume
-```
-
-Locale controls:
-
-```bash
-trackops locale get
-trackops locale set en
-trackops doctor locale
-```
+# Activation
+
+## Global install
+
+```bash
+npx skills add Baxahaun/trackops
+npm install -g trackops
+trackops --version
+```
+
+The global skill installs instructions for the agent.
+
+The `trackops` runtime is installed separately through npm so the step stays visible, auditable, and easy to verify.
+
+Before continuing:
+
+- confirm that `trackops --version` returns a valid version
+- if it does not, fix PATH or reinstall `trackops`
+- the skill must not try to install the runtime by itself
+
+## Local activation
+
+Inside a repository:
+
+```bash
+trackops init
+trackops opera install
+```
+
+`trackops opera install` also activates the project agent team:
+- `opera-skill` (coordinator)
+- `project-starter-skill`, `opera-contract-auditor`, `opera-policy-guard`
+
+By default, `trackops init` creates a split workspace with:
+
+- `app/`
+- `ops/`
+- `/.env`
+- `/.env.example`
+- `.trackops-workspace.json`
+
+## OPERA routing
+
+OPERA always starts by classifying:
+
+- technical level
+- project state
+- documentation state
+
+If the project is still early or the user is non-technical, TrackOps writes:
+
+- `ops/bootstrap/agent-handoff.md`
+- `ops/bootstrap/agent-handoff.json`
+
+The agent must produce:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+- `ops/bootstrap/open-questions.md` when needed
+
+When the quality gate passes, OPERA compiles:
+
+- `ops/contract/operating-contract.json`
+- `ops/genesis.md`
+- `ops/policy/autonomy.json`
+
+Resume with:
+
+```bash
+trackops opera bootstrap --resume
+```
+
+Locale controls:
+
+```bash
+trackops locale get
+trackops locale set en
+trackops doctor locale
+```
+
+## Uninstall
+
+Global:
+
+```bash
+npx skills remove --global trackops -y
+npm uninstall -g trackops
+```
+
+Local:
+
+- there is no `trackops uninstall` command yet
+- review and remove `.trackops-workspace.json`, `ops/`, and `app/.env` if it was only the bridge
+- do not delete `/.env` or `/.env.example` without checking whether the project still needs them

package/skills/trackops/locales/en/references/troubleshooting.md

@@ -1,55 +1,73 @@
-# Troubleshooting
-
-## Missing prerequisites
-
-- Install Node 18+ if Node is missing or too old.
-- Install a Node distribution that includes npm if npm is missing.
-
-## The skill is installed, but `trackops` does not start
-
-- Confirm that the global skill exists:
-  `npx skills add Baxahaun/trackops`
-- Install or reinstall the runtime explicitly:
-  `npm install -g trackops`
-- Verify:
-  `trackops --version`
-- If the binary still does not respond:
-  - check Node.js (`>= 18`)
-  - check that `npm` exists and works
-  - check PATH and reopen the terminal
-
-## Explicit runtime installation fails
-
-- Re-run `npm install -g trackops`.
-- If `npm` errors, fix that first; the skill cannot continue without the CLI.
-- If the issue is global permissions, use the recommended method for your system or a user-controlled npm prefix.
-
-## OPERA routed bootstrap to the agent
-
-This is expected when:
-
-- the user is non-technical
-- the project is still in idea stage
-- documentation is weak
-
-Use:
-
-```bash
-trackops opera handoff --print
-trackops opera bootstrap --resume
-```
-
-## Resume does not complete
-
-TrackOps will not invent missing context.
-
-Check that both files exist and contain usable data:
-
-- `ops/bootstrap/intake.json`
-- `ops/bootstrap/spec-dossier.md`
-
-## Environment looks inconsistent
-
-- Run `trackops env status`.
-- Run `trackops env sync`.
-- If bridge mode is `copy`, do not edit `app/.env` directly.
+# Troubleshooting
+
+## Missing prerequisites
+
+- Install Node 18+ if Node is missing or too old.
+- Install a Node distribution that includes npm if npm is missing.
+
+## The skill is installed, but `trackops` does not start
+
+- Confirm that the global skill exists:
+  `npx skills add Baxahaun/trackops`
+- Install or reinstall the runtime explicitly:
+  `npm install -g trackops`
+- Verify:
+  `trackops --version`
+- If the binary still does not respond:
+  - check Node.js (`>= 18`)
+  - check that `npm` exists and works
+  - check PATH and reopen the terminal
+
+## Explicit runtime installation fails
+
+- Re-run `npm install -g trackops`.
+- If `npm` errors, fix that first; the skill cannot continue without the CLI.
+- If the issue is global permissions, use the recommended method for your system or a user-controlled npm prefix.
+
+## OPERA routed bootstrap to the agent
+
+This is expected when:
+
+- the user is non-technical
+- the project is still in idea stage
+- documentation is weak
+
+Use:
+
+```bash
+trackops opera handoff --print
+trackops opera bootstrap --resume
+```
+
+## Resume does not complete
+
+TrackOps will not invent missing context.
+
+Check that both files exist and contain usable data:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+
+## Environment looks inconsistent
+
+- Run `trackops env status`.
+- Run `trackops env sync`.
+- If bridge mode is `copy`, do not edit `app/.env` directly.
+
+## I want to remove TrackOps completely
+
+- Remove the global skill:
+  `npx skills remove --global trackops -y`
+- Remove the global runtime:
+  `npm uninstall -g trackops`
+- Inside the repository, local removal is still manual:
+  - review `.trackops-workspace.json`
+  - review `ops/`
+  - review `app/.env` if it was only the bridge
+- Do not delete `/.env` or `/.env.example` before checking whether the project still depends on them
+
+## `opera-skill` is missing from the project
+
+- Confirm that OPERA is installed: `trackops opera status`
+- If the skill is missing: `trackops skill install opera-skill`
+- Verify: `trackops skill list` should show `opera-skill` first

package/skills/trackops/locales/en/references/workflow.md

@@ -1,32 +1,55 @@
-# Workflow
-
-Precondition:
-
-- the global skill is already installed
-- `trackops --version` responds correctly
-- the repository was already activated with `trackops init`
-
-Use TrackOps when the repository is already managed and you need day-to-day operations.
-
-1. Run `trackops status`.
-2. Run `trackops next`.
-3. Move task state with `trackops task ...`.
-4. Run `trackops sync` after meaningful changes.
-5. Run `trackops env status` when credentials matter.
-
-Operational rules:
-
-- in split workspaces, use `ops/project_control.json` as the source of truth
-- generated operational docs live in `ops/`
-- product code lives in `app/`
-- real secrets live in `/.env`
-- public environment contract lives in `/.env.example`
-- `app/.env` is only a compatibility bridge
-
-If OPERA is installed:
-
-- `ops/contract/operating-contract.json` holds the machine contract
-- `ops/genesis.md` holds the compiled human view
-- `ops/policy/autonomy.json` holds the executable autonomy policy
-- `ops/bootstrap/` holds onboarding artifacts
-- `ops/.agent/hub/` and `ops/.agents/skills/` hold managed agent artifacts
+# Workflow
+
+Precondition:
+
+- the global skill is already installed
+- `trackops --version` responds correctly
+- the repository was already activated with `trackops init`
+
+Use TrackOps when the repository is already managed and you need day-to-day operations.
+
+1. Run `trackops status`.
+2. Run `trackops next`.
+3. Move task state with `trackops task ...`.
+4. Run `trackops sync` after meaningful changes.
+5. Run `trackops env status` when credentials matter.
+
+Operational rules:
+
+- in split workspaces, use `ops/project_control.json` as the source of truth
+- generated operational docs live in `ops/`
+- product code lives in `app/`
+- real secrets live in `/.env`
+- public environment contract lives in `/.env.example`
+- `app/.env` is only a compatibility bridge
+
+If OPERA is installed:
+
+- `ops/contract/operating-contract.json` holds the machine contract
+- `ops/genesis.md` holds the compiled human view
+- `ops/policy/autonomy.json` holds the executable autonomy policy
+- `ops/bootstrap/` holds onboarding artifacts
+- `ops/.agents/skills/opera-skill/` coordinates the agent team
+- `ops/.agents/skills/` contains the other project specialists
+- `ops/.agent/hub/` holds the main agent configuration
+
+## Project agent team
+
+When OPERA is installed, a team of specialized agents is activated:
+
+- `opera-skill` — coordinator. Decides phase, state, delegation, and blocking.
+- `project-starter-skill` — discovery and structuring
+- `opera-contract-auditor` — operating contract audit
+- `opera-policy-guard` — risk control
+
+Additional skills available:
+
+- `commiter` — commit formatting
+- `changelog-updater` — changelog updates
+
+Management commands:
+
+    trackops skill list
+    trackops skill catalog
+    trackops skill install <name>
+    trackops skill remove <name>