trackops 1.0.1 → 1.1.0

package/skills/trackops/references/troubleshooting.md

@@ -0,0 +1,34 @@
+# Troubleshooting
+
+## Missing prerequisites
+
+- If Node is missing or older than 18, install Node 18+ first.
+- If npm is missing, install a Node distribution that includes npm.
+
+## skills cannot find the TrackOps skill
+
+- Install from the repository root:
+  `npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y`
+- Confirm the remote repository already contains the latest committed skill changes.
+- Remember that skills installs from committed Git state, not from uncommitted local changes.
+
+## Global npm install failed
+
+- Re-run `node scripts/bootstrap-trackops.js` and inspect stderr.
+- If npm global permissions are blocked, configure a user-writable npm prefix instead of relying on `sudo`.
+
+## Runtime cannot be verified
+
+If installation succeeds but `trackops` is still not executable:
+
+- Check whether the npm global bin directory is on `PATH`.
+- Re-open the terminal after updating shell profile settings.
+- Re-run `node scripts/bootstrap-trackops.js` once `trackops --version` works.
+
+## Workspace environment looks inconsistent
+
+If a split workspace is active and tools do not see the expected environment file:
+
+- Run `trackops env status` to inspect required, present, and missing keys without exposing values.
+- Run `trackops env sync` to recreate `/.env`, `/.env.example`, and the `app/.env` bridge.
+- If bridge mode is `copy`, do not edit `app/.env` directly; TrackOps regenerates it from the root `.env`.

package/skills/trackops/references/workflow.md

@@ -0,0 +1,20 @@
+# Workflow
+
+Once TrackOps is active in a repository, operate in this order:
+
+1. Run `trackops status` to inspect focus, phase, blockers, and repo state.
+2. Run `trackops next` to identify the next ready task.
+3. Update task state with `trackops task ...` as work progresses.
+4. Run `trackops sync` after meaningful changes so generated docs stay aligned.
+5. Run `trackops env status` when the project depends on credentials or external services.
+
+Operational rules:
+
+- In split workspaces, use `ops/project_control.json` as the source of truth.
+- In legacy repos, use `project_control.json` at repo root.
+- In split workspaces, generated operational docs live under `ops/`.
+- Product code lives under `app/`.
+- Use `/.env` for real secrets and `/.env.example` for the public environment contract.
+- `app/.env` is only a compatibility bridge.
+- If OPERA is installed, use `ops/genesis.md`, `ops/.agent/hub/`, and `ops/.agents/skills/_registry.md` as managed framework artifacts.
+- Keep the global skill layer separate from the local project layer.

package/skills/trackops/scripts/bootstrap-trackops.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const EXIT_CODES = {
+  READY: 0,
+  PREREQ: 1,
+  INSTALL: 2,
+  UNVERIFIABLE: 3,
+};
+
+function getNpmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function readSkillConfig() {
+  const skillFile = path.join(__dirname, "..", "skill.json");
+  return JSON.parse(fs.readFileSync(skillFile, "utf8"));
+}
+
+function getHomeDir() {
+  return process.env.TRACKOPS_BOOTSTRAP_HOME || os.homedir();
+}
+
+function getPrefixOverride() {
+  return process.env.TRACKOPS_BOOTSTRAP_PREFIX || null;
+}
+
+function getInstallSource(config) {
+  return process.env.TRACKOPS_BOOTSTRAP_INSTALL_SOURCE || `${config.npmPackage}@${config.trackopsVersion}`;
+}
+
+function parseMajor(version) {
+  const major = Number(String(version || "").split(".")[0]);
+  return Number.isFinite(major) ? major : null;
+}
+
+function hasSupportedNode() {
+  const major = parseMajor(process.versions.node);
+  return major != null && major >= 18;
+}
+
+function spawnChecked(command, args, extra = {}) {
+  const shell = process.platform === "win32" && /\.(cmd|bat)$/i.test(command);
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    shell,
+    ...extra,
+  });
+}
+
+function spawnNpm(args, extra = {}) {
+  return spawnSync(getNpmCommand(), args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: process.platform === "win32",
+    ...extra,
+  });
+}
+
+function resolvePrefixExecutables(prefix) {
+  if (!prefix) return [];
+  if (process.platform === "win32") {
+    return [
+      path.join(prefix, "trackops.cmd"),
+      path.join(prefix, "trackops.exe"),
+      path.join(prefix, "trackops"),
+    ];
+  }
+  return [path.join(prefix, "bin", "trackops")];
+}
+
+function buildVerificationTargets(prefix) {
+  const targets = [{ command: "trackops", via: "path" }];
+  for (const candidate of resolvePrefixExecutables(prefix)) {
+    targets.push({ command: candidate, via: "prefix" });
+  }
+  return targets;
+}
+
+function readInstalledVersion(prefix) {
+  for (const target of buildVerificationTargets(prefix)) {
+    const result = spawnChecked(target.command, ["--version"]);
+    if (result.error || result.status !== 0) continue;
+    const version = String(result.stdout || "").trim();
+    if (version) {
+      return { version, command: target.command, via: target.via };
+    }
+  }
+  return null;
+}
+
+function verifyRuntime(expectedVersion, prefix) {
+  const installed = readInstalledVersion(prefix);
+  if (!installed) {
+    return { ok: false, reason: "missing-command" };
+  }
+  if (installed.version !== expectedVersion) {
+    return { ok: false, reason: "version-drift", installed };
+  }
+
+  const help = spawnChecked(installed.command, ["help"]);
+  if (help.error || help.status !== 0) {
+    return { ok: false, reason: "help-failed", installed };
+  }
+
+  return { ok: true, installed };
+}
+
+function ensureNpmAvailable() {
+  const result = spawnNpm(["--version"]);
+  return !result.error && result.status === 0;
+}
+
+function runInstall(config, prefix) {
+  const installSource = getInstallSource(config);
+  const args = ["install", "-g"];
+  if (prefix) {
+    args.push("--prefix", prefix);
+  }
+  args.push(installSource);
+
+  const result = spawnNpm(args);
+  return { ...result, installSource };
+}
+
+function writeRuntimeStamp(config, verification) {
+  const runtimeDir = path.join(getHomeDir(), ".trackops");
+  const runtimeFile = path.join(runtimeDir, "runtime.json");
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  const payload = {
+    skill: config.name,
+    skillVersion: config.skillVersion,
+    runtimePackage: config.npmPackage,
+    runtimeVersion: config.trackopsVersion,
+    bootstrapPolicy: config.bootstrapPolicy,
+    supportedAgentsV1: config.supportedAgentsV1,
+    verifiedAt: new Date().toISOString(),
+    verifiedWith: verification.installed.via,
+    executable: verification.installed.command,
+  };
+  fs.writeFileSync(runtimeFile, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+function printInstallGuidance(prefix) {
+  if (prefix) {
+    console.error(`TrackOps was installed under the custom prefix '${prefix}'.`);
+    console.error("Use that prefix's executable or add it to PATH before trying again.");
+    return;
+  }
+
+  console.error("TrackOps was installed but could not be executed from PATH.");
+  console.error("Add your npm global bin directory to PATH, reopen the terminal, and retry.");
+}
+
+function main() {
+  const config = readSkillConfig();
+  const prefix = getPrefixOverride();
+
+  if (!hasSupportedNode()) {
+    console.error("TrackOps requires Node.js 18 or newer.");
+    process.exit(EXIT_CODES.PREREQ);
+  }
+
+  if (!ensureNpmAvailable()) {
+    console.error("npm is required to bootstrap the TrackOps runtime.");
+    process.exit(EXIT_CODES.PREREQ);
+  }
+
+  const current = verifyRuntime(config.trackopsVersion, prefix);
+  if (current.ok) {
+    writeRuntimeStamp(config, current);
+    console.log(`TrackOps runtime ${config.trackopsVersion} is already ready.`);
+    process.exit(EXIT_CODES.READY);
+  }
+
+  const install = runInstall(config, prefix);
+  if (install.error || install.status !== 0) {
+    console.error(`Failed to install ${install.installSource}.`);
+    if (install.stderr) {
+      console.error(install.stderr.trim());
+    }
+    process.exit(EXIT_CODES.INSTALL);
+  }
+
+  const verification = verifyRuntime(config.trackopsVersion, prefix);
+  if (!verification.ok) {
+    printInstallGuidance(prefix);
+    process.exit(EXIT_CODES.UNVERIFIABLE);
+  }
+
+  writeRuntimeStamp(config, verification);
+  console.log(`TrackOps runtime ${config.trackopsVersion} is ready.`);
+  process.exit(EXIT_CODES.READY);
+}
+
+main();

package/skills/trackops/skill.json

@@ -0,0 +1,29 @@
+{
+  "name": "trackops",
+  "shortDescription": "Global TrackOps skill for local project orchestration and operational automation with AI agents.",
+  "description": "Installs TrackOps as a global skill, prepares your agent for local project orchestration, ensures the runtime on first use, and guides per-project activation with optional OPERA.",
+  "skillVersion": "1.1.0",
+  "trackopsVersion": "1.1.0",
+  "npmPackage": "trackops",
+  "bootstrapPolicy": "first_use",
+  "supportedAgentsV1": [
+    "antigravity",
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "github-copilot",
+    "kiro-cli"
+  ],
+  "distribution": {
+    "source": "Baxahaun/trackops",
+    "skill": "trackops",
+    "fullDepth": true
+  },
+  "repository": {
+    "provider": "github",
+    "owner": "Baxahaun",
+    "repo": "trackops",
+    "skillPath": "skills/trackops"
+  }
+}

package/templates/opera/en/agent.md

@@ -0,0 +1,26 @@
+# Project Agent: {{PROJECT_NAME}}
+
+## Identity
+You are the primary agent for **{{PROJECT_NAME}}**. You operate under the O.P.E.R.A. v3.0 protocol.
+
+## Source of Truth
+Your source of truth is `genesis.md`. Before making any architectural or implementation decision, read it first.
+For operational tracking and backlog state, use `project_control.json`.
+
+## Behavior
+- Follow the behavior rules defined in `genesis.md`.
+- Respect the autonomy matrix to determine which actions are allowed.
+- Manage tasks and states from `project_control.json`.
+- Do not edit `task_plan.md`, `progress.md`, or `findings.md` manually; regenerate them with `trackops sync`.
+
+## Available Skills
+Check `.agents/skills/_registry.md` to see installed skills.
+You can also discover new skills with `trackops skill catalog`.
+
+## Work Cycle
+1. Run `trackops status` at the beginning of each work block.
+2. Read `genesis.md` to understand the data and rules.
+3. Use `trackops next` to inspect the prioritized queue.
+4. Before implementing, mark the task with `trackops task start <task-id>`.
+5. Use the router in `.agent/hub/router.md` to choose the right skill.
+6. When you finish, move the task to `review`, `complete`, or `block`, then run `trackops sync`.

package/templates/opera/en/genesis.md

@@ -0,0 +1,79 @@
+# {{PROJECT_NAME}} — Genesis
+
+> **The Constitution of the project.** This document is the source of truth. Before making any architectural or implementation decision, consult this file. If a script contradicts what is defined here, the script is wrong.
+
+---
+
+## 1. Desired Outcome
+
+_What is the single desired outcome of this project?_
+
+> {{DESIRED_OUTCOME}}
+
+---
+
+## 2. External Integrations
+
+_Which external services do we need? Are credentials ready?_
+
+| Service | Status | Key / Config |
+|---------|--------|--------------|
+{{SERVICES_TABLE}}
+
+---
+
+## 3. Source of Truth
+
+_Where does the primary data live?_
+
+> {{SOURCE_OF_TRUTH}}
+
+---
+
+## 4. Payload
+
+_How and where should the final result be delivered?_
+
+> {{PAYLOAD}}
+
+---
+
+## 5. Behavior Rules
+
+_Domain constraints, tone, and specific rules._
+
+{{BEHAVIOR_RULES}}
+
+---
+
+## Data Schema
+
+> **Data-first rule**: this schema must exist before any code is written.
+
+```json
+{{DATA_SCHEMA}}
+```
+
+---
+
+## Architectural Invariants
+
+_Non-negotiable technical decisions. Changing them requires explicit approval._
+
+{{ARCHITECTURAL_INVARIANTS}}
+
+---
+
+## Pipeline
+
+_Document the dependency graph between tools._
+
+{{PIPELINE_ITEMS}}
+
+---
+
+## Templates
+
+_References to output templates defined under `templates/`._
+
+{{TEMPLATE_ITEMS}}

package/templates/opera/en/references/autonomy-and-recovery.md

@@ -0,0 +1,23 @@
+# Autonomy and Recovery
+
+Use this reference to decide when the agent can continue autonomously and when it must stop for confirmation.
+
+## Red level
+
+Ask for confirmation before:
+- Changing `genesis.md` in a way that alters the contract.
+- Deleting persistent data.
+- Creating repositories or external resources.
+- Deploying to production.
+
+## Green level
+
+Proceed autonomously for:
+- Reading and editing local source files.
+- Running tests and checks.
+- Updating operational docs.
+- Repairing deterministic errors after a bounded number of attempts.
+
+## Recovery rule
+
+If a later phase invalidates an earlier decision, document the proposed change first, request approval, and only then update `genesis.md` and the operational record.

package/templates/opera/en/references/opera-cycle.md

@@ -0,0 +1,62 @@
+# The O.P.E.R.A. Cycle — Complete Reference
+
+This document describes each phase, its rules, its procedures, and its Definition of Done.
+
+---
+
+## O — Orchestrate
+
+Answer the five discovery questions, define the input/output schema in `genesis.md`, document behavior rules, and make sure the plan is approved before moving forward.
+
+### Definition of Done
+- [ ] Discovery questions answered.
+- [ ] Input/output schema defined in `genesis.md`.
+- [ ] Behavior rules documented in `genesis.md`.
+- [ ] `task_plan.md` reviewed and accepted.
+
+---
+
+## P — Prove
+
+Validate credentials, run minimal connectivity checks, and confirm that external systems return data that matches the schema in `genesis.md`.
+
+### Definition of Done
+- [ ] Required credentials verified.
+- [ ] Connectivity tests executed and passing.
+- [ ] Response shapes validated against `genesis.md`.
+- [ ] Findings documented.
+
+---
+
+## E — Establish
+
+Build the three-layer structure: SOPs in `architecture/`, atomic tools in `tools/`, and explicit dependency flow in `genesis.md`.
+
+### Definition of Done
+- [ ] SOPs written.
+- [ ] Tools implemented.
+- [ ] Dependency graph documented.
+- [ ] Integration tests passing.
+
+---
+
+## R — Refine
+
+Validate outputs against templates and ensure delivery formats match the expected payload.
+
+### Definition of Done
+- [ ] Outputs validated against templates.
+- [ ] Delivery formats reviewed.
+- [ ] UI review completed when applicable.
+
+---
+
+## A — Automate
+
+Clean temporary artifacts, configure triggers, deploy the final logic, and run a smoke test in the target environment.
+
+### Definition of Done
+- [ ] `.tmp/` cleaned.
+- [ ] Deployment completed.
+- [ ] Triggers configured.
+- [ ] Smoke test passing.

package/templates/opera/en/registry.md

@@ -0,0 +1,28 @@
+# Skills Registry — {{PROJECT_NAME}}
+
+> Index of installed skills in this project. Managed automatically by `trackops skill`.
+
+---
+
+## Installed Skills
+
+_No skills installed yet. Use `trackops skill install <name>` to add one._
+
+---
+
+## How to Use a Skill
+
+1. Identify the context in `.agent/hub/router.md`.
+2. Open the corresponding `SKILL.md`.
+3. Follow the workflow defined in that skill.
+
+---
+
+## Management
+
+```bash
+trackops skill list
+trackops skill catalog
+trackops skill install <name>
+trackops skill remove <name>
+```

package/templates/opera/en/router.md

@@ -0,0 +1,39 @@
+# Skills Router
+
+## Purpose
+This file defines the routing rules between the main agent and the available skills. When the agent detects a specific context, it should consult these rules and choose the right skill.
+
+## Routing Rules
+
+### Context: Code commit
+- **Trigger**: The user asks for a commit or a code change has just been completed.
+- **Skill**: `commiter`
+- **Action**: Use the skill to format the commit message.
+
+### Context: Post-commit
+- **Trigger**: A successful commit has just happened.
+- **Skill**: `changelog-updater`
+- **Action**: Run the changelog update flow.
+
+### Context: Project initialization
+- **Trigger**: The user wants to create a new project.
+- **Skill**: `project-starter-skill` (global)
+- **Action**: Run the full initialization protocol.
+
+### Context: Operational tracking
+- **Trigger**: A work block is about to start, resume, or close.
+- **Skill**: No external skill.
+- **Action**: Run `trackops status`, take the next task with `trackops next`, and keep `project_control.json` as the operational source of truth.
+
+## Adding New Rules
+
+Use this format for each new rule:
+
+```markdown
+### Context: [description]
+- **Trigger**: [what activates the rule]
+- **Skill**: [skill name]
+- **Action**: [what the agent should do]
+```
+
+When a new skill is installed with `trackops skill install <name>`, add its routing rule here.