pirl-framework-cli 0.0.0-stage → 1.0.0

package/bundled-framework/files/.agents/roles/process-auditor.role.md

@@ -0,0 +1,62 @@
+---
+id: .agents/roles/process-auditor
+kind: role
+version: 1.3.2
+status: active
+---
+
+# process-auditor
+
+Evaluates a completed layer run: reconstructs the decisions of each role and of
+the coordinator, finds wrong decisions, identifies the root cause and rewrites
+the rules correctly. When it runs and how the result is reported belong to the
+[router's Self-evaluation and improvement section](../instructions/layered-task-execution.instructions.md#self-evaluation-and-improvement);
+how causes are classified, how fixes are made and the record belong to the
+[self-evaluation instructions](../instructions/self-evaluation.instructions.md),
+which it reads in full before evaluating.
+
+## Questions the role answers
+
+- What was each role assigned, what did it decide, based on which sources and
+  rules?
+- Which decision is wrong against the request, the source or a contract?
+- Read to the letter, do the loaded rules lead to the right decision?
+- Has this issue been fixed before, and which cause did that fix target?
+
+## How it works
+
+- Reconstruct decisions from the output, the Implementation Record or the
+  report, and the sources the role used. Do not evaluate by impression.
+- Read the rules at exactly the version the run used, per `framework_ref`, not
+  the current version.
+- Test the rule against the scenario that caused the issue as an agent reading
+  it for the first time: does the rule cover this case, is it ambiguous, does it
+  conflict with another rule?
+- Look up earlier records by `issue_key` and by rule before concluding the
+  cause. Keep the `issue_key` of an existing issue so the trail of earlier fixes
+  is not lost.
+- When rewriting a rule: fix it where it is owned, replace the wrong passage
+  instead of piling on reminders, and write concrete conditions and actions in
+  the general form described in the
+  [Framework maintenance section](../instructions/standalone-and-maintenance.instructions.md#framework-maintenance).
+  Separate the issue from the event: ask which kind of situation causes it,
+  then write the rule for that kind. Sweep other files that reference that rule.
+
+## Common warning signs
+
+- Blaming the instructions when the rule was clear and the role did not follow it.
+- Piling on a reminder instead of fixing the sentence that caused the issue.
+- Overfitting a fix to one case and breaking a similar scenario.
+- Writing a rule tied to one run's repository, host, value, date or quote, so it
+  cannot be reused in another project.
+- Giving an old issue a new `issue_key`.
+- Copying into its own report what a role or record says about a mismatch or a
+  gap (for example documentation differing from the source) without checking it
+  against the source itself, or without stating that it is unchecked.
+- Loosening a safety rule to get past one blocked run.
+
+## Boundaries with other roles
+
+Does not edit product output, Plans or reports itself; output defects are
+returned to the owning role. Does not re-grade QGs in place of the verification
+roles.

package/bundled-framework/files/.agents/roles/solution-architect.role.md

@@ -0,0 +1,53 @@
+---
+id: .agents/roles/solution-architect
+kind: role
+version: 1.2.1
+status: active
+---
+
+# solution-architect
+
+Settles API and data contracts, ownership of data and decisions, the permission
+model, and the boundaries and dependencies between pieces of work.
+
+## Questions the role answers
+
+- Who owns this data or decision, and who may only read it?
+- What is the contract between the parts: input, output, errors, permissions,
+  backward compatibility?
+- Does the change break existing consumers, including consumers in another
+  repository the user works with?
+- Which part must be finished before which, and can they be separated for
+  independent acceptance?
+
+## How it works
+
+- Read the existing contracts in the source and documentation before proposing
+  a new contract.
+- State clearly what already exists, what needs to change, and who owns each
+  change. For documents that several pieces of work edit, the piece of work that
+  adds, changes or removes a value, symbol or file updates every passage of the
+  documentation that mentions it, including exhaustive listings.
+- Distinguish real dependencies (needing a concrete output of another part)
+  from false ones (merely editing the same file).
+- Re-read the criteria of the parts to find hidden dependency cycles: part B
+  needs part A, but A's criteria need B.
+- For permissions: determine who may do what on which data, and on which side
+  it is checked.
+
+## Common warning signs
+
+- Treating two parts as independent because no dependency is declared, while
+  they edit the same symbol or decision.
+- Creating an abstraction or a new layer just to split the work neatly.
+- Making end-to-end criteria a condition of a prerequisite part.
+- Splitting a shared document by section, column or topic, so the piece of work
+  that changes a value does not edit the passage stating that value, and that
+  passage is wrong once the work is done.
+- Overlooking consumers that call through events, configuration or another
+  repository.
+
+## Boundaries with other roles
+
+Business behavior belongs to `business-analyst`; execution-path details in code
+belong to `code-analyst`.

package/bundled-framework/files/.agents/roles/technical-writer.role.md

@@ -0,0 +1,68 @@
+---
+id: .agents/roles/technical-writer
+kind: role
+version: 1.5.0
+status: active
+---
+
+# technical-writer
+
+Writes and updates documentation that must match the source: the repository's
+context documentation, contract documents, indexes, specification status tables.
+
+## Questions the role answers
+
+- What do readers, including agents, need to know to decide correctly?
+- What in the existing documentation is wrong compared with the source?
+- Which other documents still describe the old behavior?
+
+## How it works
+
+- Take facts from the source and contracts, not from old documentation.
+- Every claim has a file/symbol source.
+- A fact lives in only one place; other places point to it.
+- Record known gaps explicitly instead of guessing.
+- Keep one term for one meaning throughout the documentation.
+- The sentence is the unit of a claim. When changing part of a sentence, check
+  every claim in the whole sentence, including clauses kept from the old
+  version: the old version is not a source.
+- Quantities, formulas or ratios stated in words must be recalculated from their
+  definition in the source (expressions, tokens, input values) and compared with
+  the description. When the description can be read two ways (for example "half
+  of A plus B" and "half of (A plus B)"), write the formula with the input values
+  and the result.
+- A sentence stating a rule, limit or scope ("at most", "always", "never",
+  "only", "every", a number) must hold for every variant that declares that
+  value in the source (theme, language, viewport, environment, configuration)
+  and agree with the other sections of the same document. A description applied
+  to a whole group of elements must hold for each element after the change,
+  including elements the change itself just added. This group covers sentences
+  combining several elements, lists that claim to be complete, and the lead-in
+  sentence, heading or column labels above a table or list; quantifier words in
+  them (for example "some", "shared", "every", "only") are claims about each
+  row or item. Read the description, then check it against each row or item in
+  turn, not just each cell on its own; for a row that does not fit the
+  description, fix the description or move that row out of the group. Find
+  every place of use by symbol or property, then check each variant and each
+  element, not just the default variant or the first example.
+- Do not edit historical records such as settled Plans or Review reports.
+
+## Common warning signs
+
+- Copying content from another file, so the two copies drift apart.
+- Describing intent instead of the source's actual behavior.
+- Missing an index or status table.
+- Long, ornate sentences with several ideas in one sentence.
+- Changing part of a sentence and keeping the rest from the old version without
+  checking it against the source, or copying a quantity or formula stated in
+  words without recalculating it.
+- Rewriting a rule based on the default variant or the first example, so it is
+  wrong for another variant, element or place of use, or contradicts a table of
+  values in another section.
+- Checking each cell of a table or each item of a list but not checking its
+  lead-in sentence or heading against each row, so the group description is
+  wrong for one row.
+
+## Boundaries with other roles
+
+Changes to code behavior belong to `backend-developer` or `frontend-developer`.

package/bundled-framework/files/.agents/roles/ux-designer.role.md

@@ -0,0 +1,46 @@
+---
+id: .agents/roles/ux-designer
+kind: role
+version: 1.1.0
+status: active
+---
+
+# ux-designer
+
+Settles and checks what the user sees: screens, display states, interaction
+flows, UI strings for each language, layout per viewport.
+
+## Questions the role answers
+
+- What does the user see in each state: normal, empty, loading, error, locked,
+  input validation error?
+- Which action leads to which state, and where does closing a dialog return to?
+- Does the text in each language fit the layout; at desktop and mobile
+  viewports is there overflow, overlap or horizontal scrolling; are focus and
+  the Esc key right when dialogs stack?
+
+## How it works
+
+- List display states from the contract and the business flow, not just the
+  success state.
+- Take the list of languages and viewports from the repository's context
+  documentation; if missing, take them from the i18n configuration and CSS
+  breakpoints.
+- Write UI criteria as state and layout logic checkable on the source and the
+  screenshots, not as impressions.
+- When looking at layout screenshots: compare each failed point with the same
+  screen in the state without the change, to separate new defects from
+  pre-existing ones. Also check what screenshots cannot show: the language of
+  the text, focus, the ability to scroll after closing a dialog.
+
+## Common warning signs
+
+- Considering only the success state.
+- Overlooking the language with the longest strings.
+- Accepting a screenshot set missing the error state or a viewport.
+- Subjective criteria such as "beautiful" or "easy to use".
+
+## Boundaries with other roles
+
+Writing UI code belongs to `frontend-developer`; business logic belongs to
+`business-analyst`.

package/bundled-framework/files/.skills/pirl-implement/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: pirl-implement
+description: Runs the Implement layer of the PIRL framework. Carries out exactly one Plan task in its target repository, or repairs it per a Review report for the same task, has separate verification roles conclude every quality gate by reasoning on the source, and writes the Implementation Record into the Plan file. Use only when the user's own words ask to implement a named Plan or to fix per a named Review report. Do not use to write a Plan, to review, for work outside a Plan or to edit the framework itself.
+metadata:
+  id: .skills/pirl-implement
+  kind: skill
+  layer: implement
+  version: 1.1.2
+---
+
+# Implement
+
+Carries out one Implement layer run: a first run of a Plan task, or a repair run
+per a Review report. The
+[Implement contract](../../.agents/instructions/implement.instructions.md) owns
+the decisions, when layout verification with mocks applies, and the exit
+conditions; the
+[layout verification instructions](../../.agents/instructions/layout-verification.instructions.md)
+own how it is done; the
+[router](../../.agents/instructions/layered-task-execution.instructions.md) owns
+the shared contracts (verification by reasoning, functional tests);
+[AGENTS.md](../../AGENTS.md) owns the core rules, roles and target repository.
+This skill owns the order of the steps, the Implementation Record format and
+the helper scripts. Where a step names a
+section, that section decides.
+
+## When to use
+
+- The user's own words ask to implement a Plan task, or to fix per a Review
+  report, per the
+  [conditions for opening a layer](../../AGENTS.md#choosing-a-layer).
+- Not for writing a Plan ([`pirl-plan`](../pirl-plan/SKILL.md)), checking an
+  implementation ([`pirl-review`](../pirl-review/SKILL.md)), work assigned outside a
+  Plan ([standalone task](../../.agents/instructions/standalone-and-maintenance.instructions.md#standalone-tasks))
+  or [framework maintenance](../../.agents/instructions/standalone-and-maintenance.instructions.md#framework-maintenance).
+
+## Resources
+
+| Resource | Use |
+| --- | --- |
+| [`assets/implementation-record-template.md`](assets/implementation-record-template.md) | Template of the Implementation Record section |
+| [`references/implementation-record-format.md`](references/implementation-record-format.md) | Where the record goes, how its fields are written, the layout capture directory |
+| [`scripts/add_implementation_record.py`](scripts/add_implementation_record.py) | Appends the record template to a Plan file that has none yet, with `updated_at` filled in |
+| [`scripts/new_layout_run.py`](scripts/new_layout_run.py) | Creates the directory of one layout capture run for the Plan task |
+| [`validate_layer_artifact.py`](../../.agents/evals/validate_layer_artifact.py) | Checks the Plan and its record before handoff |
+| [`layer_record.py`](../../.agents/evals/layer_record.py) | Pins the framework version, finds earlier records and writes the run's record |
+
+## Procedure
+
+Run the commands from the Hub root.
+
+1. **Open the run.** Apply the [core rules](../../AGENTS.md#core-rules) and
+   [CONTEXT.md](../../CONTEXT.md). Run
+   `python -B .agents/evals/layer_record.py start` and keep the returned
+   `framework_ref`
+   ([Timing and evaluator](../../.agents/instructions/layered-task-execution.instructions.md#timing-and-evaluator)).
+2. **Read the inputs**
+   ([contract](../../.agents/instructions/implement.instructions.md#reading-inputs-and-determining-scope)):
+   exactly the named Plan file, its Implementation Record if any, the named
+   Review report for a repair run, and the source of the Plan's `target_repo`
+   with its context documentation ([AGENTS.md](../../AGENTS.md#target-repository)).
+3. **Team.** The Plan's `implementation_roles` (or the report's `repair_roles`
+   for a repair run), then the Plan's `verification_roles`
+   ([AI Agent roles at the Implement layer](../../.agents/instructions/implement.instructions.md#ai-agent-roles-at-the-implement-layer)).
+   Delegate each role to a separate agent per the
+   [assignment principles](../../.agents/instructions/layered-task-execution.instructions.md#assignment-principles), with its role file,
+   its table row and the rows that row refers to.
+4. **Implement or repair**
+   ([contract](../../.agents/instructions/implement.instructions.md#implementing-and-repairing-per-review)),
+   with tests only under the
+   [FUT rule](../../.agents/instructions/layered-task-execution.instructions.md#functional-tests-fut-rule)
+   and the test command the target repository documents. A deviation the user
+   confirms follows
+   [Changes to the Plan confirmed by the user](../../.agents/instructions/implement.instructions.md#changes-to-the-plan-confirmed-by-the-user).
+5. **Capture the layout** when the diff changes the UI, before verification
+   ([Layout verification with mocks](../../.agents/instructions/implement.instructions.md#layout-verification-with-mocks)).
+   Each capture run gets a new directory:
+
+   ```powershell
+   python -B .skills/pirl-implement/scripts/new_layout_run.py --plan <Plan file>
+   ```
+
+6. **Verify the quality gates by reasoning**
+   ([contract](../../.agents/instructions/implement.instructions.md#verifying-quality-gates-by-reasoning)).
+   A FAIL goes back to the implementation role that owns the part, at most two
+   repairs of the same cause.
+7. **Write the Implementation Record**
+   ([Recording results](../../.agents/instructions/implement.instructions.md#recording-results),
+   [format](references/implementation-record-format.md)). When the Plan has no
+   record yet, add the template first; set the Plan's `status` to the record's
+   `status`; then validate and fix until it passes:
+
+   ```powershell
+   python -B .skills/pirl-implement/scripts/add_implementation_record.py --plan <Plan file>
+   python -B .agents/evals/validate_layer_artifact.py --kind plan --path <Plan file>
+   ```
+
+8. **Self-evaluate.** `process-auditor`, in a separate agent, evaluates the run,
+   applies improvements and writes exactly one record
+   ([Self-evaluation and improvement](../../.agents/instructions/layered-task-execution.instructions.md#self-evaluation-and-improvement));
+   output defects it finds go back to the owning implementation role within the
+   same two-repair limit:
+
+   ```powershell
+   python -B .agents/evals/layer_record.py append --input <JSON file>
+   python -B .agents/evals/layer_record.py check
+   ```
+
+9. **Clean up** temporary resources in the Hub and the target repository; keep
+   the layout capture directories
+   ([router](../../.agents/instructions/layered-task-execution.instructions.md#cleaning-up-temporary-resources-before-handoff)).
+10. **Hand off and report**
+    ([Finishing and handoff](../../.agents/instructions/implement.instructions.md#finishing-and-handoff),
+    [Reporting](../../.agents/instructions/layered-task-execution.instructions.md#reporting)).
+    Stop there: Review opens only when the user asks for it.

package/bundled-framework/files/.skills/pirl-implement/assets/implementation-record-template.md

@@ -0,0 +1,22 @@
+## Implementation Record
+- status: awaiting_confirmation | implemented | blocked | failed
+- updated_at: "{{updated_at}}"
+- changed_paths: <relative paths or []>
+- role_work: <role=status/evidence, with commands and test scope under FUT if any; ...>
+- execution_mode: <separate agent per role | self-performed in turn, with the reason delegation was not possible; with each role's actual level of independence per the assignment principles in AGENTS.md: sources read beyond the assignment, reviewers outside the role team consulted>
+- checkpoint_evidence: <checkpoint, evidence and input to continue; or N/A>
+- quality_gate_results: <QG-01=PASS|FAIL|BLOCKED per the verification role's conclusion; ...>
+- quality_gate_evidence: <each QG -> verification role, file/symbol, path traced, counterexample and conclusion>
+- layout_verification: <N/A when the diff does not change the UI; or states captured, languages, viewports, the base used for comparison (base commit and uncommitted changes counted), number of screenshots, checks passed/failed (each failed check with its cause per the layout verification instructions) and the .tmp/layout-snapshots/... directory>
+- repair_closure_evidence: <each report item -> REQ/QG, cause, solution/disposition and matching before/after evidence; or exactly N/A for the first run>
+- root_cause_revalidation: <ITEM-ID=confirmed|contradicted|blocked/evidence before the fix; or exactly N/A for the first run>
+- review_item_disposition: <FIND-01=resolved|failed|blocked/evidence; RISK-01=deferred/owner and revisit condition; BLOCK-01=unblocked|blocked|escalated/evidence; or exactly N/A for the first run>
+- plan_amendments: <each Plan edit per the "Changes to the Plan confirmed by the user" section: Plan line, old -> new value, what the user confirmed and when; or exactly N/A>
+- role_challenge_results: <role=PASS|FAIL|BLOCKED/claim, challenge and evidence; ...>
+- residual_risk: <remaining risk and impact; or none>
+- review_handoff: <Plan file, implementation target, source report if any>
+- role_selection_source: plan | <relative path of the source report>
+- effective_implementation_roles: <list of roles in order, comma-separated>
+- Next allowed owner/layer: <owner/layer>
+- Authorization condition: <input or decision for the next step>
+1. <concrete action and related paths>

package/bundled-framework/files/.skills/pirl-implement/references/implementation-record-format.md

@@ -0,0 +1,41 @@
+# Implementation Record format
+
+The `pirl-implement` skill owns how the Implementation Record is laid out and where
+the layout captures are stored. What each field must hold, and what a repair
+run records, belongs to the
+[Recording results section](../../../.agents/instructions/implement.instructions.md#recording-results)
+of the Implement contract.
+
+## Location
+
+- One `## Implementation Record` section in the Plan file, below the four Plan
+  sections, wherever the Plan file is stored.
+- `scripts/add_implementation_record.py` appends the
+  [template](../assets/implementation-record-template.md) only when the Plan has
+  no such section; an existing section is edited in place.
+
+## Fields
+
+- One `- <field>: <value>` line per field, in the order of the template,
+  followed by the numbered next actions.
+- The validator reads `status` and `updated_at` verbatim: write them exactly as
+  in the template, without backticks or a trailing period. `status` is one of
+  `awaiting_confirmation`, `implemented`, `blocked`, `failed` and equals the
+  Plan's frontmatter `status`; `updated_at` is an ISO-8601 timestamp with
+  the machine's UTC offset, quoted. The other fields are free text.
+- Fields that the contract requires to be present even when empty take exactly
+  `N/A`, as the template shows.
+
+## Layout capture directory
+
+- `.tmp/layout-snapshots/<plan-set>/<task-id>/<YYYYMMDD-HHmmss>/` under the Hub
+  root, whatever directory holds the Plan; `scripts/new_layout_run.py` creates
+  it with the current local timestamp. The `layout_verification` field names
+  it.
+
+## Placeholders in the template
+
+- `{{updated_at}}`: filled by `scripts/add_implementation_record.py`; update it
+  on every later write of the record.
+- `<…>` and the `a | b | c` alternatives: the coordinator writes the actual
+  value and keeps exactly one alternative.

package/bundled-framework/files/.skills/pirl-implement/scripts/add_implementation_record.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Append the Implementation Record template to a Plan file that has no record yet, with updated_at filled in.
+
+The record's layout is owned by ../references/implementation-record-format.md and its content by the
+Implement contract; an existing record is edited in place, so this script refuses to add a second one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parents[1]
+HUB = SKILL.parents[1]
+sys.path.insert(0, str(HUB / ".agents" / "evals"))
+from validate_layer_artifact import PLAN_SCHEMA, LayerArtifactError, read_frontmatter, resolve_path  # noqa: E402
+
+TEMPLATE = SKILL / "assets" / "implementation-record-template.md"
+RECORD = re.compile(r"(?m)^## Implementation Record\s*$")
+
+
+def add(root: Path, plan: str) -> dict[str, object]:
+    path = resolve_path(plan, root)
+    if not path.is_file():
+        raise LayerArtifactError(f"{plan} is not an existing Plan file (relative to the Hub root or absolute)")
+    metadata, body = read_frontmatter(path)
+    if metadata.get("schema") != PLAN_SCHEMA:
+        raise LayerArtifactError(f"{plan} is not a {PLAN_SCHEMA} Plan")
+    if RECORD.search(body):
+        raise LayerArtifactError(f"{plan} already has an Implementation Record; edit it in place")
+    record = TEMPLATE.read_text(encoding="utf-8").replace("{{updated_at}}", datetime.now().astimezone().isoformat(timespec="seconds"))
+    text = path.read_text(encoding="utf-8")
+    with path.open("a", encoding="utf-8", newline="\n") as handle:
+        handle.write(("" if text.endswith("\n") else "\n") + "\n" + record)
+    return {"path": plan}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--plan", required=True, help="the Plan file, relative to the Hub root or absolute")
+    parser.add_argument("--root", type=Path, default=HUB, help="Hub root (default: the Hub containing this script)")
+    args = parser.parse_args()
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    try:
+        result = {"passed": True, **add(args.root.resolve(), args.plan)}
+    except (LayerArtifactError, OSError) as exc:
+        result = {"passed": False, "errors": [str(exc)]}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-framework/files/.skills/pirl-implement/scripts/new_layout_run.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Create the directory of one layout capture run for a Plan task: .tmp/layout-snapshots/<plan-set>/<task-id>/<timestamp>/.
+
+When to capture and what to record belong to .agents/instructions/layout-verification.instructions.md; this script only
+creates a new, empty run directory under the Hub root and never reuses an earlier one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parents[1]
+HUB = SKILL.parents[1]
+sys.path.insert(0, str(HUB / ".agents" / "evals"))
+from validate_layer_artifact import PLAN_SCHEMA, LayerArtifactError, read_frontmatter, resolve_path  # noqa: E402
+
+
+
+def create(root: Path, plan: str) -> dict[str, object]:
+    path = resolve_path(plan, root)
+    if not path.is_file():
+        raise LayerArtifactError(f"{plan} is not an existing Plan file (relative to the Hub root or absolute)")
+    metadata, _ = read_frontmatter(path)
+    if metadata.get("schema") != PLAN_SCHEMA or not metadata.get("plan_set") or not metadata.get("task_id"):
+        raise LayerArtifactError(f"{plan} is not a {PLAN_SCHEMA} Plan with plan_set and task_id")
+    run = root / ".tmp" / "layout-snapshots" / str(metadata["plan_set"]) / str(metadata["task_id"]) / f"{datetime.now().astimezone():%Y%m%d-%H%M%S}"
+    run.mkdir(parents=True)
+    return {"path": run.relative_to(root).as_posix()}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--plan", required=True, help="the Plan file, relative to the Hub root or absolute")
+    parser.add_argument("--root", type=Path, default=HUB, help="Hub root (default: the Hub containing this script)")
+    args = parser.parse_args()
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    try:
+        result = {"passed": True, **create(args.root.resolve(), args.plan)}
+    except (LayerArtifactError, OSError) as exc:
+        result = {"passed": False, "errors": [str(exc)]}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-framework/files/.skills/pirl-plan/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: pirl-plan
+description: Runs the Plan layer of the PIRL framework. Turns a product request into a Plan package for one target repository, one file per task, with REQs, the approach, implementation and verification roles, and quality gates that can be proven by reasoning on the source. Use only when the user's own words ask to create, write, split or adjust a Plan. Do not use to implement or review a Plan, to answer a question, for a standalone task or to edit the framework itself.
+metadata:
+  id: .skills/pirl-plan
+  kind: skill
+  layer: plan
+  version: 1.1.2
+---
+
+# Plan
+
+Carries out one Plan layer run. The
+[Plan contract](../../.agents/instructions/plan.instructions.md) owns the
+decisions and exit conditions; the
+[router](../../.agents/instructions/layered-task-execution.instructions.md) owns
+the shared contracts; [AGENTS.md](../../AGENTS.md) owns the core rules, roles
+and target repository. This skill owns the order of the steps, the Plan file
+format and the helper script. Where a step names a section, that section
+decides.
+
+## When to use
+
+- The user's own words ask for a Plan, per the
+  [conditions for opening a layer](../../AGENTS.md#choosing-a-layer).
+- Not for carrying out a Plan ([`pirl-implement`](../pirl-implement/SKILL.md)), checking
+  an implementation ([`pirl-review`](../pirl-review/SKILL.md)), a question that only needs
+  an explanation, a
+  [standalone task](../../.agents/instructions/standalone-and-maintenance.instructions.md#standalone-tasks)
+  or [framework maintenance](../../.agents/instructions/standalone-and-maintenance.instructions.md#framework-maintenance).
+
+## Resources
+
+| Resource | Use |
+| --- | --- |
+| [`assets/plan-template.md`](assets/plan-template.md) | Template of one Plan task file |
+| [`references/plan-format.md`](references/plan-format.md) | Frontmatter fields, sections, file naming and output location |
+| [`scripts/new_plan.py`](scripts/new_plan.py) | Creates the package directory and one task file from the template, with the package name, task ID, file name and timestamp filled in |
+| [`validate_layer_artifact.py`](../../.agents/evals/validate_layer_artifact.py) | Checks the Plan structure before handoff |
+| [`layer_record.py`](../../.agents/evals/layer_record.py) | Pins the framework version at the start and writes the run's record |
+
+## Procedure
+
+Run the commands from the Hub root.
+
+1. **Open the run.** Apply the [core rules](../../AGENTS.md#core-rules) and
+   [CONTEXT.md](../../CONTEXT.md). Run
+   `python -B .agents/evals/layer_record.py start` and keep the returned
+   `framework_ref`
+   ([Timing and evaluator](../../.agents/instructions/layered-task-execution.instructions.md#timing-and-evaluator)).
+2. **Target repository.** Identify it per
+   [AGENTS.md](../../AGENTS.md#target-repository) and read its context
+   documentation.
+3. **Planning team.** Pick the roles by the "Select when" column, or keep
+   exactly the roles the user named
+   ([AI Agent roles at the Plan layer](../../.agents/instructions/plan.instructions.md#ai-agent-roles-at-the-plan-layer)).
+   Delegate each role to a separate agent per the
+   [assignment principles](../../.agents/instructions/layered-task-execution.instructions.md#assignment-principles).
+4. **Investigate and settle decisions**
+   ([contract](../../.agents/instructions/plan.instructions.md#investigating-and-settling-decisions)).
+   Ask only about missing decisions that change the result; continue the
+   independent parts.
+5. **Split the work into tasks**
+   ([contract](../../.agents/instructions/plan.instructions.md#splitting-tasks-for-separate-implementation-and-acceptance)),
+   within the [scope of work](../../.agents/instructions/plan.instructions.md#scope-of-work-source-code-documentation-and-functional-tests)
+   and with [separate implementation and verification roles](../../.agents/instructions/plan.instructions.md#separating-implementation-roles-from-verification-roles).
+6. **Write the task files** in the directory the user named, or by default under
+   the Hub root ([format](references/plan-format.md#location-and-naming)). The
+   first task starts the package; each next task joins it:
+
+   ```powershell
+   python -B .skills/pirl-plan/scripts/new_plan.py --request-slug <request-slug> --todo-slug <todo-slug> [--out-dir <dir>]
+   python -B .skills/pirl-plan/scripts/new_plan.py --plan-set <plan-set> --todo-slug <todo-slug> [--out-dir <dir>]
+   ```
+
+   Replace every `<...>` placeholder so the content is
+   [sufficient to execute](../../.agents/instructions/plan.instructions.md#content-must-be-sufficient-to-execute).
+7. **Self-review and validate**
+   ([contract](../../.agents/instructions/plan.instructions.md#self-review-before-handoff)),
+   then fix and rerun until the validator passes:
+
+   ```powershell
+   python -B .agents/evals/validate_layer_artifact.py --kind plan --path <package directory>
+   ```
+
+8. **Self-evaluate.** `process-auditor`, in a separate agent, evaluates the run,
+   applies improvements and writes exactly one record
+   ([Self-evaluation and improvement](../../.agents/instructions/layered-task-execution.instructions.md#self-evaluation-and-improvement)):
+
+   ```powershell
+   python -B .agents/evals/layer_record.py append --input <JSON file>
+   python -B .agents/evals/layer_record.py check
+   ```
+
+9. **Clean up** temporary resources
+   ([router](../../.agents/instructions/layered-task-execution.instructions.md#cleaning-up-temporary-resources-before-handoff)).
+10. **Hand off and report**
+    ([Saving and handoff](../../.agents/instructions/plan.instructions.md#saving-and-handoff),
+    [Reporting](../../.agents/instructions/layered-task-execution.instructions.md#reporting)).
+    Stop there: Implement opens only when the user asks for it.