@plainconceptsplatform/agent-harness 2.2.1 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/commands/update.js +13 -1
- package/src/content/.agents/skills/pc-make-engineer/SKILL.md +219 -219
- package/src/content/.agents/skills/pc-make-engineer/template.md +80 -81
- package/src/content/.opencode/plugins/pc-subagent-tiers.js +337 -281
- package/src/content/opencode.jsonc +41 -39
- package/src/steps/copy/fullstack-engineer.js +88 -85
- package/src/steps/copy/opencode-json.js +161 -147
- package/src/steps/metadata/index.js +4 -0
- package/src/steps/optimization/detect.js +66 -0
- package/src/utils/agent-color.js +83 -0
|
@@ -1,81 +1,80 @@
|
|
|
1
|
-
# Agent file template
|
|
2
|
-
|
|
3
|
-
The agent file is exactly this structure: frontmatter plus one identity paragraph plus the `## Abilities` section. No other sections. No other content.
|
|
4
|
-
|
|
5
|
-
```markdown
|
|
6
|
-
---
|
|
7
|
-
description: <one sentence naming the persona + top 3-5 detected technologies>
|
|
8
|
-
mode: subagent
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
- State the
|
|
50
|
-
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
6. Re-read the file to confirm all remaining `@skill-name` references are valid.
|
|
1
|
+
# Agent file template
|
|
2
|
+
|
|
3
|
+
The agent file is exactly this structure: frontmatter plus one identity paragraph plus the `## Abilities` section. No other sections. No other content.
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
---
|
|
7
|
+
description: <one sentence naming the persona + top 3-5 detected technologies>
|
|
8
|
+
mode: subagent
|
|
9
|
+
permission:
|
|
10
|
+
edit: allow
|
|
11
|
+
bash: allow
|
|
12
|
+
read: allow
|
|
13
|
+
glob: allow
|
|
14
|
+
grep: allow
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
<One paragraph: "You are a {persona} engineer specializing in {top technologies}. You own all work in {scope/files}." Keep it to 2-3 sentences max.>
|
|
18
|
+
|
|
19
|
+
## Abilities
|
|
20
|
+
- Guardrails: @pc-guardrails-generic, @pc-guardrails-project
|
|
21
|
+
- Development: <@installed-skill-1>, <@installed-skill-2>, ...
|
|
22
|
+
- Testing: <@installed-skill-for-testing>, ...
|
|
23
|
+
- Infrastructure: <@installed-skill-for-devops>, ...
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
That is the entire file: frontmatter, one identity paragraph, and the `## Abilities` section. The always-installed `pc-system-reminders` plugin loads the listed skills for every session. Replace every `<...>` placeholder with real values from your research. Remove any ability category line that has no skills assigned (besides Guardrails which is always present).
|
|
27
|
+
|
|
28
|
+
## Description quality bar
|
|
29
|
+
|
|
30
|
+
The `description:` field is the matching key for `/plan-apply`. The lead compares task domain text against agent descriptions to pick the right specialist. A weak description means the wrong engineer gets spawned.
|
|
31
|
+
|
|
32
|
+
Bad: `"A frontend engineer for React"`
|
|
33
|
+
Good: `"Frontend engineer for Ink 7 + React 19 TUI, FSD architecture, Inversify DI, design tokens, and i18n"`
|
|
34
|
+
|
|
35
|
+
Rules:
|
|
36
|
+
- Name the persona explicitly
|
|
37
|
+
- List the top 3-5 detected technologies from Step 2
|
|
38
|
+
- One sentence, no padding
|
|
39
|
+
|
|
40
|
+
## Identity paragraph
|
|
41
|
+
|
|
42
|
+
The identity paragraph sits between frontmatter and `## Abilities`. It tells the engineer who it is and what it owns in 2-3 sentences max. Not a spec, not a knowledge dump, a quick scoping statement.
|
|
43
|
+
|
|
44
|
+
Bad: 5 paragraphs of architecture details, FSD rules, design tokens, file maps, testing patterns.
|
|
45
|
+
Good: `"You are a frontend engineer specializing in terminal UI development with Ink 7 + React 19. You own all work in the FSD layers: src/app/, src/widgets/, src/features/, src/entities/, and src/shared/."`
|
|
46
|
+
|
|
47
|
+
Rules:
|
|
48
|
+
- State the persona and specialization in one sentence
|
|
49
|
+
- State what files or layers the engineer owns in one sentence
|
|
50
|
+
- Never exceed 3 sentences
|
|
51
|
+
|
|
52
|
+
## Category rules
|
|
53
|
+
|
|
54
|
+
- Development = language/framework/UI/DI skills. Testing = test/lint/typecheck skills. Infrastructure = DevOps/CI/CD/cloud skills.
|
|
55
|
+
- Only include ability categories that have at least one real skill (besides Guardrails which is always present).
|
|
56
|
+
- Name follows `{persona}-engineer` pattern (e.g. `frontend-engineer`, `backend-engineer`).
|
|
57
|
+
- Read existing agents' `color:` frontmatter first: pick a color not already used.
|
|
58
|
+
- `warning` is reserved for the lead (fullstack) engineer, the planning agent. Never assign it to a spawned specialist.
|
|
59
|
+
|
|
60
|
+
## Structural validation checklist
|
|
61
|
+
|
|
62
|
+
After writing the agent file, verify:
|
|
63
|
+
|
|
64
|
+
1. Frontmatter exists: starts with `---`, has `description`, `mode: subagent`, `permission` block. No `color`: the `pc-subagent-tiers` plugin derives one from the agent name at startup.
|
|
65
|
+
2. No `model:` field in the frontmatter. The `pc-subagent-tiers` plugin injects it.
|
|
66
|
+
3. `## Abilities` is the only `##` heading. No other `##` sections exist in the file.
|
|
67
|
+
4. One identity paragraph before `## Abilities`: 2-3 sentences max, not multiple paragraphs.
|
|
68
|
+
5. Abilities are categorized: each line starts with `- Guardrails:`, `- Development:`, `- Testing:`, or `- Infrastructure:`. No bare `@skill-name` lines.
|
|
69
|
+
6. One file only: no `.build.md`, `.fast.md`, or `.plan.md` variant was created.
|
|
70
|
+
|
|
71
|
+
If any check fails, rewrite the file to match the template exactly.
|
|
72
|
+
|
|
73
|
+
## Skill reference validation
|
|
74
|
+
|
|
75
|
+
1. Parse every `@skill-name` from the `## Abilities` section (excluding `@pc-guardrails-generic` and `@pc-guardrails-project` which are installed at init).
|
|
76
|
+
2. For each: check `.agents/skills/<skill-name>/SKILL.md` exists.
|
|
77
|
+
3. For each: check `skills-lock.json` contains the skill.
|
|
78
|
+
4. If `.agents/skills/<skill-name>/SKILL.md` exists but `skills-lock.json` is missing the entry: manually patch `skills-lock.json` using the Edit tool (same procedure as in the signal mapping reference). Re-read `skills-lock.json` to confirm it is valid JSON.
|
|
79
|
+
5. If `.agents/skills/<skill-name>/SKILL.md` is missing: try to install it: `npx skills add -y <owner/repo@skill-name>` (search `skills-lock.json` or `npx skills find` for the owner/repo). If install fails or the skill can't be found on skills.sh, remove the reference from the file, warn the user, and note it in the summary.
|
|
80
|
+
6. Re-read the file to confirm all remaining `@skill-name` references are valid.
|