@plainconceptsplatform/agent-harness 2.4.1 → 2.5.1

package/harness/.agents/skills/pc-userstory-jira/SKILL.md

@@ -1,131 +1,74 @@
----
-name: pc-userstory
-description: Parse a Jira work item and create an OpenSpec change. Use when the user provides a Jira URL or a bare issue key (e.g. PROJ-123).
-license: MIT
-compatibility: Requires openspec CLI and Atlassian CLI (acli).
-metadata:
-  author: copilots
-  version: "1.0"
----
-
-Use `acli` CLI for all Jira operations.
-
-## Atlassian CLI Setup (One-Time)
-
-Install from: https://developer.atlassian.com/cloud/acli/guides/install-acli/
-
-Authenticate:
-```bash
-# Option 1: API token (recommended for CI)
-echo <token> | acli jira auth login --site "<yoursite>.atlassian.net" --email "<email>" --token
-
-# Option 2: OAuth (interactive)
-acli jira auth login --web
-```
-
-Generate API token at: https://id.atlassian.com/manage-profile/security/api-tokens
-
-## Steps
-
-1. **Extract Issue Key** from URL
-   - `https://yoursite.atlassian.net/browse/PROJ-123` -> Key: PROJ-123
-   - `https://yoursite.atlassian.net/jira/core/projects/PROJ/issues/PROJ-123` -> Key: PROJ-123
-   - `https://yoursite.atlassian.net/browse/PROJ-123?filter=123` -> Key: PROJ-123
-   - If the user provides just `PROJ-123` without a URL, use it directly as the key.
-
-2. **Fetch Work Item**
-   ```bash
-   acli jira workitem view --key "PROJ-123"
-   ```
-
-   Parse the output for:
-   - Summary -> title
-   - Description -> proposal context
-   - Acceptance Criteria (if present in description or custom fields) -> spec requirements
-   - Labels -> tags for the OpenSpec change
-   - Status -> current state (e.g. To Do, In Progress, Done)
-   - Assignee -> who requested it
-   - Priority -> complexity hint
-
-3. **Offer to transition the Work Item to In Progress**
-
-   This writes to Jira, so ask first using the `question` tool:
-
-   ```json
-   {
-     "questions": [
-       {
-         "header": "Transition work item",
-         "question": "Move {KEY} to In Progress?",
-         "options": [
-           { "label": "yes", "description": "Transition the work item to In Progress." },
-           { "label": "no", "description": "Skip the transition." }
-         ]
-       }
-     ]
-   }
-   ```
-
-   Only if the user answers `yes` AND the status is currently "To Do" or "Backlog":
-   ```bash
-   acli jira workitem transition --key "PROJ-123" --status "In Progress"
-   ```
-   In unattended runs (`/plan-goal`), skip the question and the transition entirely.
-
-4. **Create OpenSpec Change**
-   ```bash
-   openspec new change "{slug-from-summary}"
-   ```
-
-   Write `proposal.md` with:
-   - Title: the Jira issue summary
-   - Context: mention this is Jira issue `{KEY}`, link back to the URL
-   - Requirements: extracted from description and acceptance criteria
-   - Scope: what's in/out based on the issue
-
-5. **Hand off to proposal.** Load the `pc-plan-propose` skill (interactive mode) to generate the proposal, specs, and tasks. After it completes, call the `question` tool:
-
-   ```json
-   {
-     "questions": [
-       {
-         "header": "Ready to implement",
-         "question": "Ready to implement?",
-         "options": [
-           { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
-           { "label": "no", "description": "Stop here. You can run /plan-apply later." }
-         ]
-       }
-     ]
-   }
-   ```
-
-   Wait for confirmation before loading `pc-plan-apply`.
-
-## Jira URL Patterns
-
-| URL format | Example |
-|------------|---------|
-| Browse URL | `https://yoursite.atlassian.net/browse/PROJ-123` |
-| Issue URL  | `https://yoursite.atlassian.net/jira/core/projects/PROJ/issues/PROJ-123` |
-| Board URL  | `https://yoursite.atlassian.net/jira/software/c/projects/PROJ/boards/1?selectedIssue=PROJ-123` |
-| Direct key | `PROJ-123` |
-
-## Useful Commands
-
-```bash
-# View work item
-acli jira workitem view --key "PROJ-123"
-
-# Transition work item
-acli jira workitem transition --key "PROJ-123" --status "In Progress"
-acli jira workitem transition --key "PROJ-123" --status "Done"
-
-# Search with JQL
-acli jira workitem search --jql "project = PROJ AND status = 'To Do' ORDER BY priority DESC"
-
-# Add a comment
-acli jira workitem comment create --key "PROJ-123" --body "Implementation started"
-```
-
-Jira is a backlog-only platform: it has no code repos or PRs. PR creation and code review use the repo platform (GitHub or Azure DevOps) configured separately.
+---
+name: pc-userstory
+description: Parse a Jira work item and create an OpenSpec change. Use when the user provides a Jira URL or a bare issue key (e.g. PROJ-123).
+license: MIT
+compatibility: Requires openspec CLI and Atlassian CLI (acli).
+metadata:
+  author: copilots
+  version: "1.0"
+---
+
+Turn a Jira issue into an OpenSpec change, then hand the change to `pc-plan-propose`. Jira is backlog-only: it has no repositories and no pull requests, so shipping runs on whichever repo platform the project configured.
+
+## Rules
+
+- Issue data comes from `acli`, never from a page fetch or a browser (denied by `pc-system-reminders`). An `acli` that cannot authenticate is a blocker to report; install and login are documented at https://developer.atlassian.com/cloud/acli/guides/install-acli/.
+- Never transition the work item without asking, and never transition one that is not in `To Do` or `Backlog`. Moving somebody's ticket is visible to their whole team.
+- In an unattended run, skip the question and the transition rather than resolving it yes.
+- Never load `pc-plan-apply` until the user has said yes.
+
+## Contracts
+
+The key is `PROJ-123`, taken from `/browse/PROJ-123`, `/jira/core/projects/PROJ/issues/PROJ-123`, `?selectedIssue=PROJ-123`, or given bare.
+
+```bash
+acli jira workitem view --key "PROJ-123"
+```
+
+From the output take the summary (title), the description (context), acceptance criteria wherever they live (spec requirements), labels, status, assignee and priority.
+
+```bash
+acli jira workitem transition --key "PROJ-123" --status "In Progress"
+```
+
+Ask before that one:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Transition work item",
+      "question": "Move {KEY} to In Progress?",
+      "options": [
+        { "label": "yes", "description": "Transition the work item to In Progress." },
+        { "label": "no", "description": "Skip the transition." }
+      ]
+    }
+  ]
+}
+```
+
+Then create the change, whose `proposal.md` names the Jira key and links back to it:
+
+```bash
+openspec new change "{slug-from-summary}"
+```
+
+Load `pc-plan-propose` (interactive) and, once it returns, ask:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Ready to implement",
+      "question": "Ready to implement?",
+      "options": [
+        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
+        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
+      ]
+    }
+  ]
+}
+```
+
+Also available: `acli jira workitem search --jql "..."` and `acli jira workitem comment create --key "PROJ-123" --body "..."`.

package/harness/.opencode/commands/init.md

@@ -1,5 +1,5 @@
----
-description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
----
-
-Load the `pc-repo-initialize` skill and follow every step defined in it.
+---
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
+---
+
+Load the `pc-repo-initialize` skill.

package/harness/.opencode/commands/make-architecture.md

@@ -1,5 +1,5 @@
----
-description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time.
----
-
-Load the `pc-make-architecture` skill and follow every step defined in it.
+---
+description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time.
+---
+
+Load the `pc-make-architecture` skill.

package/harness/.opencode/commands/make-design.md

@@ -1,5 +1,5 @@
----
-description: Generate or update DESIGN.md by analyzing the codebase design system. Safe to run at any time.
----
-
-Load the `pc-make-design` skill and follow every step defined in it.
+---
+description: Generate or update DESIGN.md by analyzing the codebase design system. Safe to run at any time.
+---
+
+Load the `pc-make-design` skill.

package/harness/.opencode/commands/make-engineer.md

@@ -1,5 +1,5 @@
----
-description: Create a custom engineer agent via persona-driven interactive design
----
-
-Load the `pc-make-engineer` skill and follow every step defined in it.
+---
+description: Create a custom engineer agent via persona-driven interactive design
+---
+
+Load the `pc-make-engineer` skill.

package/harness/.opencode/commands/make-evidence-scaffold.md

@@ -1,5 +1,5 @@
----
-description: One-time scaffold of a project-specific visual-evidence harness (deterministic capture + assertions + manifest + publisher) that /ops-evidence and /plan-goal delegate to.
----
-
-Load the `pc-make-evidence-scaffold` skill and follow every step defined in it.
+---
+description: DEPRECATED. Per-project evidence scaffolds are gone; run /ops-evidence instead.
+---
+
+Load the `pc-make-evidence-scaffold` skill.

package/harness/.opencode/commands/make-guardrails.md

@@ -1,5 +1,5 @@
----
-description: Generate or update a pc-guardrails-project skill from ARCHITECTURE.md and relevant project files.
----
-
-Load the `pc-make-guardrails` skill and follow every step defined in it.
+---
+description: Generate or update a pc-guardrails-project skill from ARCHITECTURE.md and relevant project files.
+---
+
+Load the `pc-make-guardrails` skill.

package/harness/.opencode/commands/make-user-model.md

@@ -1,5 +1,5 @@
----
-description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override.
----
-
-Load the `pc-make-user-model` skill and follow every step defined in it.
+---
+description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override.
+---
+
+Load the `pc-make-user-model` skill.

package/harness/.opencode/commands/plan-apply.md

@@ -1,9 +1,9 @@
----
-description: Implement tasks from a plan: works with OpenSpec proposals and in-conversation plans.
----
-
-Load the `pc-plan-apply` skill and execute it in **interactive mode** with `start_from: branch` (the full protocol, including branch creation).
-
-Input:
-
-$ARGUMENTS
+---
+description: "Implement tasks from a plan: works with OpenSpec proposals and in-conversation plans."
+---
+
+Load the `pc-plan-apply` skill and execute it in **interactive mode** with `start_from: branch`.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/plan-goal.md

@@ -1,5 +1,5 @@
----
-description: Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering.
----
-
-Load the `pc-plan-goal` skill and follow every step defined in it.
+---
+description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering."
+---
+
+Load the `pc-plan-goal` skill.

package/harness/.opencode/commands/plan-quick.md

@@ -1,5 +1,5 @@
----
-description: Quick plan: analyze the codebase and create a task checklist using the Todo pane. No files, no OpenSpec.
----
-
-Load the `pc-plan-quick` skill and follow every step defined in it.
+---
+description: "Quick plan: analyze the codebase and create a task checklist using the Todo pane. No files, no OpenSpec."
+---
+
+Load the `pc-plan-quick` skill.

package/harness/.opencode/commands/plan-story.md

@@ -1,9 +1,9 @@
----
-description: Write a detailed, repo-aware user story from a feature idea or need.
----
-
-Load the `pc-plan-story` skill and follow every step defined in it.
-
-Input:
-
-$ARGUMENTS
+---
+description: Write a detailed, repo-aware user story from a feature idea or need.
+---
+
+Load the `pc-plan-story` skill.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/repo-audit.md

@@ -1,5 +1,5 @@
----
-description: Audit every configured source root against the fullstack engineer's guardrails and abilities. Read-only.
----
-
-Load the `pc-repo-audit` skill and follow every step defined in it.
+---
+description: Audit every configured source root against the fullstack engineer's guardrails and abilities. Read-only.
+---
+
+Load the `pc-repo-audit` skill.

package/harness/.opencode/commands/repo-initialize.md

@@ -1,5 +1,5 @@
----
-description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
----
-
-Load the `pc-repo-initialize` skill and follow every step defined in it.
+---
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
+---
+
+Load the `pc-repo-initialize` skill.

package/harness/.opencode/commands/repo-onboard.md

@@ -1,5 +1,5 @@
----
-description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system.
----
-
-Load the `pc-repo-onboard` skill and follow every step defined in it.
+---
+description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system.
+---
+
+Load the `pc-repo-onboard` skill.

package/harness/.opencode/commands/repo-verify.md

@@ -1,5 +1,5 @@
----
-description: Verify current-branch changes, plus immutable dependency installs, builds, and tests for every discovered project.
----
-
-Load the `pc-repo-verify` skill and follow every step defined in it.
+---
+description: Verify current-branch changes, plus immutable dependency installs, builds, and tests for every discovered project.
+---
+
+Load the `pc-repo-verify` skill.

package/harness/.opencode/plugins/pc-subagent-monitor.js

@@ -1,14 +1,28 @@
 // pc-subagent-monitor: tracks spawned subagents in .opencode/harness-run.json for
-// live TUI display and crash recovery. Never throws: monitor failures must
-// not break a session.
+// live TUI display and crash recovery, and holds a wave to agents.maxConcurrent.
+//
+// It throws in exactly one case: to deny a spawn over the cap. Every other
+// failure, including its own bugs, is swallowed — a monitor that breaks the run
+// it is watching is worse than no monitor.
 
 import fs from "node:fs/promises"
 import path from "node:path"
 
+// A spawn that has been allowed but whose session has not appeared yet. A wave
+// is one assistant turn, and opencode calls tool.execute.before for every
+// task() in that turn before the first child session exists, so counting live
+// sessions alone would let an entire wave through whatever the cap says.
+//
+// The slot is released when the session lands, and expires otherwise:
+// tool.execute.after never fires for a tool that threw, so a failed spawn must
+// not hold a slot for the rest of the run.
+const PENDING_TTL_MS = 15_000
+
 export const PcSubagentMonitor = async ({ directory, client }) => {
   const root = directory || process.cwd()
   const statePath = path.join(root, ".opencode", "harness-run.json")
   const state = { updatedAt: null, agents: {} }
+  const pending = []
 
   try {
     const prev = JSON.parse(await fs.readFile(statePath, "utf-8"))
@@ -94,7 +108,69 @@ export const PcSubagentMonitor = async ({ directory, client }) => {
     }
   }
 
+  let _capCache = null
+  async function maxConcurrent() {
+    if (_capCache) return _capCache
+    let configured = 3
+    try {
+      const raw = await fs.readFile(path.join(root, ".opencode", "harness.json"), "utf-8")
+      const value = JSON.parse(raw)?.agents?.maxConcurrent
+      if (Number.isFinite(value)) configured = value
+    } catch {
+      // no config yet; the CLI's own default is 3
+    }
+    _capCache = Math.min(5, Math.max(1, Math.trunc(configured)))
+    return _capCache
+  }
+
+  function runningFor(parentID) {
+    return Object.values(state.agents)
+      .filter(entry => entry?.status === "running" && !entry.stale && entry.parentID === parentID)
+      .length
+  }
+
+  function livePending(parentID) {
+    const now = Date.now()
+    for (let i = pending.length - 1; i >= 0; i--) {
+      if (now - pending[i].at > PENDING_TTL_MS) pending.splice(i, 1)
+    }
+    return pending.filter(entry => entry.parentID === parentID).length
+  }
+
+  function releasePending(parentID) {
+    const index = pending.findIndex(entry => entry.parentID === parentID)
+    if (index !== -1) pending.splice(index, 1)
+  }
+
   return {
+    // The cap was prose in pc-plan-apply ("you enforce the cap"), which asked
+    // the lead to count its own parallel calls. Six disjoint groups and a cap
+    // of three is exactly the moment a model stops counting.
+    "tool.execute.before": async (input) => {
+      if (input?.tool !== "task") return
+
+      let cap
+      let live
+      try {
+        pruneStale()
+        cap = await maxConcurrent()
+        live = runningFor(input.sessionID) + livePending(input.sessionID)
+        if (live < cap) {
+          pending.push({ parentID: input.sessionID, at: Date.now() })
+          return
+        }
+      } catch (error) {
+        // Compute inside the try, deny outside it, so this catch can never
+        // swallow the one exception the hook is meant to raise.
+        console.error(`[harness] concurrency check failed open: ${error?.message}`)
+        return
+      }
+
+      throw new Error(
+        `[harness] ${live} subagents are already in flight and agents.maxConcurrent is ${cap}.\n` +
+        "Collect a running worker before spawning another. A denied spawn is not a failed task: re-issue it in the next wave.",
+      )
+    },
     event: async ({ event }) => {
       try {
         if (!event?.type?.startsWith("session.")) return
@@ -103,9 +179,13 @@ export const PcSubagentMonitor = async ({ directory, client }) => {
 
         if (event.type === "session.created" && info.parentID) {
           pruneStale()
+          // The spawn this session came from no longer needs its pending slot;
+          // the session itself is now what the cap counts.
+          releasePending(info.parentID)
 
           state.agents[info.id] = {
             agent: info.agent ?? null,
+            parentID: info.parentID,
             model: await modelForAgent(info.agent),
             tasks: parseTasks(info.title),
             title: info.title ?? null,

package/harness/.opencode/plugins/pc-subagent-tiers.js

@@ -6,7 +6,8 @@
 // Agent topology:
 //   build.md / plan.md      mode: primary   the only agents a human selects.
 //                                           Both are fullstack-engineer with a
-//                                           tier model; plan cannot edit.
+//                                           tier model; plan can neither edit
+//                                           nor spawn.
 //   fullstack-engineer.md   mode: subagent  the shared body of build and plan,
 //                                           and the fallback worker.
 //   *-engineer.md           mode: subagent  specialists, spawned by task().
@@ -22,8 +23,10 @@ import path from "node:path"
 const TIERS = ["build", "fast", "plan"]
 
 // The two primaries, and the tier each takes its model from. plan denies edit
-// so a planning session cannot mutate the tree; bash stays allowed because the
-// planning skills shell out to git and openspec to read state.
+// and task: a planning session cannot mutate the tree itself, and it cannot
+// spawn a worker that would do it on its behalf. bash stays allowed because the
+// planning skills shell out to git and openspec to read state, and
+// pc-system-reminders holds it to inspection commands.
 //
 // Their colours are theme keywords rather than derived hexes, and they are
 // fixed: these are the two agents a human picks, so they should look the same
@@ -39,7 +42,7 @@ const PRIMARIES = {
     tier: "plan",
     color: "warning",
     description: "Explore and plan without touching the tree. Read-only: proposes work for build to carry out.",
-    permission: { edit: "deny" },
+    permission: { edit: "deny", task: "deny" },
   },
 }
 
@@ -228,8 +231,8 @@ export const PcSubagentTiers = async ({ directory }) => {
     if (model) lines.push(`model: ${model}`)
     lines.push(`color: ${yamlColor(spec.color)}`)
     lines.push('permission:')
-    // plan denies edit; everything else stays allowed so the planning skills can
-    // still read the tree, shell out to git and openspec, and spawn engineers.
+    // plan denies edit and task; the rest stays allowed so the planning skills
+    // can still read the tree and shell out to git and openspec.
     lines.push(`  edit: ${spec.permission?.edit ?? 'allow'}`)
     for (const key of ['bash', 'read', 'glob', 'grep', 'question', 'todowrite', 'task', 'skill']) {
       lines.push(`  ${key}: ${spec.permission?.[key] ?? 'allow'}`)