view release on metacpan or  search on metacpan

agent/skills/chorus-create-project.md  view on Meta::CPAN

# Skill — chorus-create-project

> Trigger: `chorus-create-project <sandbox-name> <output-file.json> [--batch] [--strategy iso|edges|cross|scale]`
> Agent: `architect`
>
> `<sandbox-name>`: sandbox containing a KB produced by `chorus-feed`
> `<output-file.json>`: name of the JSON file to create in `$SANDBOX/`
>                       (ignored in `--batch` and `--strategy` modes — filenames are fixed, see Phase 6)
> `--batch`: generate the full coverage suite (4 files) in one pass (see Phase 6)
> `--strategy <slug>`: generate exactly **one** file from the coverage suite, identified by slug.
>                      Safe alternative to `--batch` when session timeout is a risk.
>                      Slugs: `iso` → `projet-rules-iso.json` · `edges` → `projet-edges.json`
>                             `cross` → `projet-cross.json`  · `scale` → `projet-scale.json`
>
> **Choosing between `--batch` and `--strategy`:**
> - Use `--batch` for small/medium sandboxes (≤ 5 agents, short KB files).
> - Use `--strategy` when `--batch` times out: run 4 sequential sessions, one slug each.
>   The KB reading (Phase 0) is shared — use the coverage table from the first session
>   as context for the subsequent ones to avoid re-reading the full KB each time.
>
> **Single responsibility: create a valid project JSON file.**
> This skill reads the sandbox KB to infer types, slots, and thresholds,
> then generates a JSON file populated with both conforming AND non-conforming
> elements that explore the variety of the domain.
>
> Prerequisites: `chorus-feed <sandbox-name>` must have been run beforehand.
>
> ⚠️ **Sources to use — strict order:**
> 1. `$SANDBOX/agent/chorus/index.org` → Frame types, pipeline, namespace
> 2. `$SANDBOX/agent/chorus/<slug>.org` → mandatory slots, thresholds, helpers
> 3. An existing `projet-*.json` file in `$SANDBOX/` → reference format
>
> â›” **Never read** `Helpers.pm`, `Feed.pm`, `Agent/*.pm`, `Expert.pm`, `run.pl`
> to create a project. These files are derived from the org KBs — the canonical
> source is always the org KB.

---

## Phase 0 — Read the KB (single source)

### 0.0 Sandbox inventory (first tool call — token keepalive)

**Before reading any file**, read the directory tree $SANDBOX/` immediately.

This serves two purposes:
1. Acquires the full sandbox structure early (agents list, rules dirs, existing JSON files)
2. Ensures at least one tool call happens before any long reading+thinking cycle,
   keeping the IDE token active from the very start.

Use this inventory to:
- Confirm the list of `<slug>.org` files to read in 0.2
- Detect any existing `projet-*.json` file (for Phase 0.3)
- Know which `rules/<slug>/` directories exist (for the keepalive calls in 0.2)

### 0.1 Pipeline index

Read `$SANDBOX/agent/chorus/index.org`:
- Perl namespace of the project
- Ordered list of agents (slug, module, pos)
- Global slot dictionary (if present)

### 0.2 KB of each agent

For each agent, apply this two-step sequence:

1. **Read** `$SANDBOX/agent/chorus/<slug>.org` and extract:

| KB Section | What to extract |
|---|---|
| `Catalogue des Frames` | Element types + mandatory/optional slots per type |
| `Dictionnaire des slots` | Exact slot names, value types, valid domains |
| `Slots de ciblage` | Slot(s) that Feed must set for the agent to see the Frame |
| `Helpers Perl` (KB section) | Normative tables: thresholds, ranges, admitted classes |
| `Contraintes & Pitfalls` | Edge cases to cover in the project |

2. **Immediately after** (no thinking between the two calls): read the 
   directory tree $SANDBOX/rules/<slug>/ to list the rule files for this agent.

> **`type_element` — canonical name guard:** while reading the KB, verify that
> the element type slot is named **`type_element`** in the `Dictionnaire des slots` of
> each `<slug>.org`. Then, immediately after reading the directory tree of
> `$SANDBOX/rules/<slug>/`, read one representative `.yml` file from that agent and
> verify that its `FIND`/`CHERCHER` block uses `attribut: type_element` (not
> `element_type`, `type`, `kind`, or any variant).
> If a different name is found → **stop and report** before generating any JSON:
> ```
> â›” Slot name mismatch detected:
>    KB org uses '<found_org_name>' / YAML uses 'attribut: <found_yaml_name>'
>    but the project JSON template uses "type_element".
>    Fix: rename to `type_element` in the KB org (Slot dictionary), all YAML rules,
>    and any existing project JSON files before proceeding.
>    (See chorus-feed.md § Naming Conventions and chorus-engine-yaml.md § YAML Rules checklist)
> ```
> Do not generate a JSON that will silently produce 0 processed elements.

> **Why the immediate tool call:** Opus extended thinking after reading a dense KB file
> can be long enough to expire the IDE token. Reading the directory tree right after
> each read resets the token TTL and produces a useful rules inventory at no extra cost.
>
> **Rule:** threshold tables are in the `Helpers Perl` section of the org KBs —
> they are supposed to be identical to the code in `Helpers.pm`. Do not open `Helpers.pm`.
> ⚠️ **If any value looks suspicious** (e.g. an ep_min that seems too low for the zone,
> an R_min that doesn't match standard memory), flag it before generating elements and
> ask the user to verify org ↔ Helpers.pm parity — a divergence here corrupts all
> generated JSON files (see `chorus-feed.md` Helpers Checklist rule "Org KB parity").

### 0.3 Reference format

If a `projet-*.json` file exists in `$SANDBOX/`, read its first 30 lines
to confirm the JSON format (keys `projet`, `description`, `elements`, fields `id`, `type_element`).
Do not read individual elements — types and slots are in the KB.

---

agent/skills/chorus-create-project.md  view on Meta::CPAN

Check:
- [ ] JSON syntactically valid (no trailing comma, correct quotes)
- [ ] Each element has `id` and `type_element`
- [ ] â›” **`type_element` name cross-check:** verify that the JSON key used for the element type
      (`"type_element"`) matches exactly the `attribut:` name in the YAML `FIND`/`CHERCHER` blocks
      of the sandbox rules. A mismatch → SOLVED pipeline with 0 processed elements.
      If a mismatch is detected here at validation time → do not run `perl run.pl`;
      report the mismatch and correct the YAML rules or the JSON key first.
- [ ] All types are present in `%SLOTS_REQUIS` of `Feed.pm`
  (or verify in the `Catalogue des Frames` of the KB — equivalent source)
- [ ] No slot computed by the pipeline (result slots, qualification/evaluation status slots) is provided
- [ ] Non-conforming values actually cross the threshold (recompute if in doubt)
- [ ] ⚠️ **For CONFORMING cases: verify ALL criteria of ALL rules** that apply
  to the type — not just the primary criterion.
  An element may pass the first criterion and fail a secondary criterion of the same rule.
  For each type, list all criteria from the KB and check them one by one.
  Annotate each verified criterion in the `_note_calc` field of the JSON.
- [ ] ⚠️ **Universal rules (no type guard) — check ALL agents:** some rules apply to every
  element regardless of type (e.g. moisture check in Qualification, pb_thickness in Fire).
  For every conforming element, verify that ALL slots touched by universal rules across
  the full pipeline hold valid values. A `moisture_content: 0` or a missing fire slot
  silently breaks a conforming element even when its primary rule is unrelated.
  These checks span agent boundaries — enumerate universal rules from every agent KB.

---

## Phase 5 — Execute and verify

```bash
perl $SANDBOX/run.pl $SANDBOX/<fichier.json>
```

Check:
- [ ] No Feed crash (unknown type, missing slot)
- [ ] `Unprocessed: 0` — every element must reach the final conformity status
- [ ] Expected KO elements are indeed `NON_CONFORME` with the correct reason
- [ ] Expected OK elements are indeed `CONFORME`
- [ ] `Pipeline : SOLVED ✅`

If an expected KO element is CONFORME → investigate:
1. Does the CONDITION of the targeted rule exclude this type? ← most common pitfall
2. Does the EXCEPTION short-circuit the rule? (slot already set by a preceding rule)
3. Does the provided value actually cross the threshold? (recompute)

---

## Phase 6 — Multi-file mode (`--batch` or `--strategy`)

> `--batch`: **orchestrator mode** — the current agent runs Phases 0+1 only, then spawns
>            4 sub-agents (one per strategy) via `eca__spawn_agent`. Each sub-agent has
>            its own session and token — no timeout risk from extended thinking between files.
>
> `--strategy <slug>`: **single-file mode** — the current agent generates exactly one
>            targeted file directly (same workflow as a sub-agent). Use when running one
>            strategy at a time manually, or when resuming a failed `--batch`.

### 6.1 `--batch` — Orchestrator workflow

#### Step 1 — Run Phases 0+1

Run Phase 0 in full (inventory + KB reading + keepalives) and Phase 1 (coverage table).
Do NOT generate any JSON here — stop after the coverage table is built.

#### Step 2 — Build the compact KB summary

Distil the KB into a self-contained block (≤ 60 lines).
This is the **only** KB context passed to sub-agents — do NOT pass raw org file content.

```
SANDBOX: <absolute path>
NAMESPACE: <Perl namespace>
AGENTS: <slug1>, <slug2>, …
TYPES: <type1>, <type2>, …
TARGETING_SLOT_AGENT1: <slot>

THRESHOLDS:
  <slot>: <value> [<unit>] — <source §>
  …

RULES:
  <agent_slug> R<NN> (<slot_written>) : <threshold or condition summary>
  …

COVERAGE TABLE:
  <type> | OK: N | KO: N | variants: …
  …
```

#### Step 3 — Spawn 4 sub-agents

Spawn 4 sub-agents via `eca__spawn_agent` (agent: `general`).
They can run in parallel if the IDE permits, otherwise spawn sequentially.

Use this task template for each, substituting `<slug>`, `<FILE>`, and `<PREFIX>`:

| slug | FILE | PREFIX |
|---|---|---|
| `iso` | `projet-rules-iso.json` | `I-` |
| `edges` | `projet-edges.json` | `E-` |
| `cross` | `projet-cross.json` | `X-` |
| `scale` | `projet-scale.json` | `S-` |

```
You are a chorus-create-project sub-agent.

STRATEGY: <slug>
TARGET FILE: <SANDBOX>/<FILE>
ID PREFIX: <PREFIX>  (prepend to every element id, e.g. <PREFIX>TYPE-OK-01)

━━━ KB SUMMARY (do NOT read any file — all context is here) ━━━
<compact KB summary from Step 2>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STRATEGY GOAL:
  iso   → 1 OK + 1 KO per rule, one rule exercised per element  (≈ 2 × N_rules elements)
  edges → threshold−ε (KO) / threshold (OK) / threshold+ε for every continuous slot
  cross → elements that trigger multiple rules simultaneously (1–3 per rule pair)
  scale → ≥ 100 elements, all types × all classes/zones (termination stress test)

YOUR TASKS:
1. Compute element values from the threshold tables in the KB summary (never by intuition).