pirl-framework-cli 0.0.0-stage → 1.0.0

package/bundled-framework/files/.agents/instructions/self-evaluation.instructions.md

@@ -0,0 +1,146 @@
+---
+name: "Self-evaluation Instructions"
+description: "How process-auditor classifies the issues of a layer run, applies improvements and writes the run's record. Read in full by process-auditor; read by the coordinator only when it self-evaluates in mode: self."
+applyTo: ".agents/instructions/**/*,.skills/**/*,.agents/roles/process-auditor.role.md"
+metadata:
+  id: ".agents/instructions/self-evaluation"
+  kind: "instruction"
+  version: "1.0.0"
+  status: "active"
+---
+
+# Self-evaluation Instructions
+
+This file holds the procedure of the
+[router's Self-evaluation and improvement section](layered-task-execution.instructions.md#self-evaluation-and-improvement),
+which owns when a Plan, Implement or Review run self-evaluates, who evaluates
+and how the result is reported. `process-auditor` reads this whole file in
+every layer run; the coordinator reads it only when it self-evaluates in
+`mode: self`. Standalone tasks and framework maintenance do not apply it.
+
+## Issues and causes
+
+An issue is a decision or output that is wrong against the request, the
+source, a contract or a rule, with evidence. Each issue records the role (or
+`coordinator`), the wrong decision, the related rule as `file#section`, the
+evidence and an `issue_key`: a kebab-case key describing the issue; an issue
+already present in an earlier record keeps its existing key.
+
+Before classifying, look up earlier records with `layer_record.py query --issue-key <key>`
+and `layer_record.py query --rule <file#section>`. Classify by evidence, not
+by how many times it repeated:
+
+| Cause | When | Required improvement |
+| --- | --- | --- |
+| `instruction` | Reading the rules at exactly `framework_ref`: no rule covers this case, a rule leads to the wrong decision, two rules conflict, or a rule is ambiguous | Fix the rule |
+| `ineffective_fix` | An earlier record fixed an issue with the same key or the same rule, and the issue still happens | Determine why that fix failed (wrong cause, does not cover this case, the role does not load the rule), then replace or revert that fix itself, without stacking another. Record `prior_fix` |
+| `input` | The rule is right but the input is missing or wrong: the Plan lacks a decision, the target repository's context documentation is incomplete or wrong | Fix where the input is produced: the rule of the layer or skill that produces it. A gap in the target repository's context documentation lies outside the framework: record that improvement `pending_user` with reason `repository` and propose it to the user as a standalone task in that repository |
+| `execution` | The rule is clear, was loaded and leads to the right decision, but the role did not follow it | Increase enforcement: put that point in the role's "Done when" column in the layer file's table, or assign a verification role to check exactly that point |
+
+## Thorough improvement
+
+Applies in `mode: agent`, and in `mode: self` per the
+[Self-evaluation when `mode: self`](#self-evaluation-when-mode-self) section.
+Every issue must have an improvement applied within the run. There are no
+off-limits areas and no waiting for proposals:
+
+1. Before editing any framework file, read the
+   [standalone and maintenance instructions](standalone-and-maintenance.instructions.md). Fix every place that owns
+   the cause: layer files, skills, role files,
+   `AGENTS.md`, the router, framework tools with their tests. The only
+   improvement not applied this way is one in a target repository's context
+   documentation, handled per the `input` row above.
+2. Sweep the whole framework for places still describing the old behavior and
+   fix them in the same run.
+3. Replace the wrong passage with concrete conditions and actions; do not pile
+   on reminders, and write it in the general form described in the
+   [Framework maintenance section](standalone-and-maintenance.instructions.md#framework-maintenance).
+4. Bump the `version` of files that have one.
+5. Re-read the edited part against the three scenarios of the
+   [Framework maintenance section](standalone-and-maintenance.instructions.md#framework-maintenance).
+6. Run the commands in [Framework checks](standalone-and-maintenance.instructions.md#framework-checks)
+   that match what was edited.
+
+Mandatory exception: never loosen the
+[safety rules](../../AGENTS.md#safety-rules-and-self-improvement).
+An improvement that would loosen a safety rule is not applied: record
+`pending_user` with reason `safety` and ask the user.
+
+## Self-evaluation when `mode: self`
+
+The self-evaluation itself does not edit framework files: every improvement in
+its record is recorded as `pending_user` with reason `mode_self`, and the tool
+rejects `applied` in `mode: self`. Improvements that touch no safety rule do not
+need the user's confirmation ([AGENTS.md](../../AGENTS.md#workflow)), so within
+the same run the coordinator applies each improvement that touches no safety
+rule as user-directed framework maintenance, following the six steps of the
+[Thorough improvement](#thorough-improvement) section. It then writes a new
+record whose `supersedes` points to the self-evaluation record, with empty
+`issues` and `fixes`, and a `summary` stating each `issue_key`, the file and
+section edited, old → new version, the check commands run and a reference to
+the authorization in `AGENTS.md`. The final response reports this in the
+"Self-improvement" section, without asking.
+
+An improvement that touches a safety rule (loosening, narrowing, removing or
+working around it) is not applied: the record states `pending_user` with reason
+`safety`; the final response states the issue, cause, rule, the concrete change
+and the evidence of that improvement in the "Self-improvement" section, and the
+user's decision (apply, skip, or re-evaluate with a separate agent) is one point
+in "Needs confirmation"
+([CONTEXT.md](../../CONTEXT.md#5-closing-block-needs-confirmation-and-proposals));
+no other separate section is opened for that decision. The run that carries out
+that choice writes a new record whose `supersedes` points to the old record.
+
+## Record
+
+Each run writes exactly one record with
+`python -B .agents/evals/layer_record.py append --input <JSON file>`
+(or by passing JSON on stdin). On Windows, use `--input` with a UTF-8 file so
+non-ASCII text is not corrupted. The tool adds `schema`, `record_id`,
+`recorded_at` and rejects malformed records; if the record is rejected, the run
+is not complete. Do not edit the JSONL files by hand; correct a record with a
+new record that has `supersedes`. Records are handoff output, stored at
+`.agents/evals/records/<layer>/<YYYY-MM-DD>.jsonl`. That directory is ignored
+by Git because records describe the user's projects: they stay on the local
+machine and are never committed, and the tool still reads them for `query` and
+`check`.
+
+| Field | Content |
+| --- | --- |
+| `layer` | `plan`, `implement` or `review` |
+| `framework_ref` | The value `start` returned at the start of the run |
+| `task` | `plan_set`, `task_ids`; Review adds `report_file` |
+| `target_repo` | As in the Plan |
+| `outcome` | `status` (Plan: `ready`, `draft`, `blocked`; Implement: the Implementation Record status; Review: `completed`, `blocked`) and `summary`; Review adds `verdict` |
+| `roles` | Each participating role: `role`, `mode`, `assignment`, `result` (`PASS`, `FAIL`, `BLOCKED`) |
+| `audit` | `role: process-auditor`, `mode`, `result` (`clean` or `issues`) |
+| `issues` | Each issue: `id` (`ISSUE-NN`), `issue_key`, `role`, `record` (null; or the record in `evaluates` when the issue belongs to the re-evaluated run), `cause`, `decision`, `rule`, `evidence`, `prior_fix` (`<record_id>#FIX-NN`, only for `ineffective_fix`) |
+| `fixes` | Each improvement: `id` (`FIX-NN`), the `issues` it addresses, `status` (`applied` or `pending_user`), `reason` when pending (`mode_self`, `safety` or `repository`), `files` (`path`, `section`), `summary`, `checks` (check commands that were run, required when `applied`) |
+| `evaluates` | Review: the record of the reviewed Implement run; other layers write null |
+| `supersedes` | The record being corrected, or null |
+
+A complete record for a Plan run, as the input of `append`. Values in `<...>`
+are placeholders; `framework_ref` is the object `start` returned, copied as is.
+A run with no issues writes `issues: []`, `fixes: []` and
+`audit.result: "clean"`; a Review record also has `task.report_file` and
+`outcome.verdict`.
+
+```json
+{
+  "layer": "plan",
+  "framework_ref": {"commit": "<commit>", "files": {"<path>": "<hash>"}},
+  "task": {"plan_set": "<plan-set>", "task_ids": ["T01"]},
+  "target_repo": "<as in the Plan>",
+  "outcome": {"status": "ready", "summary": "<summary>"},
+  "roles": [{"role": "code-analyst", "mode": "agent", "assignment": "<assignment>", "result": "PASS"}],
+  "audit": {"role": "process-auditor", "mode": "agent", "result": "issues"},
+  "issues": [{"id": "ISSUE-01", "issue_key": "<kebab-case-key>", "role": "coordinator", "record": null,
+              "cause": "instruction", "decision": "<wrong decision>", "rule": "<file#section>", "evidence": "<evidence>"}],
+  "fixes": [{"id": "FIX-01", "issues": ["ISSUE-01"], "status": "applied",
+             "files": [{"path": "<framework file>", "section": "<section>"}], "summary": "<change>", "checks": ["<command>"]}],
+  "evaluates": null,
+  "supersedes": null
+}
+```
+
+Every issue must belong to at least one improvement.

package/bundled-framework/files/.agents/instructions/standalone-and-maintenance.instructions.md

@@ -0,0 +1,230 @@
+---
+name: "Standalone Tasks and Framework Maintenance Instructions"
+description: "Standalone tasks and how the framework itself is maintained: its structure and owners, the role catalog, the constraints on roles and the checks; read only in the cases listed at the top."
+applyTo: ".agents/**/*,.skills/**/*,AGENTS.md,CONTEXT.md"
+metadata:
+  id: ".agents/instructions/standalone-and-maintenance"
+  kind: "instruction"
+  version: "1.0.3"
+  status: "active"
+---
+
+# Standalone tasks and framework maintenance
+
+Read this file only in these cases:
+
+- a standalone task: the [Standalone tasks](#standalone-tasks) section;
+- framework maintenance the user assigns: the whole file;
+- inside a Plan, Implement or Review run, only when a framework improvement is
+  applied (`process-auditor`, or the coordinator in `mode: self`), per the
+  [Thorough improvement](self-evaluation.instructions.md#thorough-improvement)
+  section of the self-evaluation instructions.
+
+Plan, Implement and Review runs do not read it otherwise; a question that only
+needs an explanation reads it only when the question is about the framework's
+structure or maintenance.
+
+## Standalone tasks
+
+A standalone task is work the user assigns directly that closes within that
+same run, outside the Plan → Implement → Review chain: writing or updating
+documentation on request, an investigation with durable output, a small fix
+the user specifies. Carrying out a Plan task is still Implement, even with a
+single role. A question that only needs an explanation and creates no durable
+output is answered directly (step 3 of
+[Choosing a layer](../../AGENTS.md#choosing-a-layer)).
+
+No Review is scheduled, so the person doing the work closes the loop within the session:
+
+1. Complete the delivery within exactly the scope the user assigned, under the
+   core rules.
+2. Self-verify: check the output against the request and the authoritative
+   sources, and pick a counterexample that could refute the most important
+   claim; fix wrong output before reporting. Record it as self-verification,
+   not an independent review.
+3. Report separately the delivery result, how it was verified and what remains
+   unknown. Do not create a Plan or report unless the user asks. Standalone
+   tasks write no self-evaluation record; only the three layers write one, per
+   the [Self-evaluation and improvement section](layered-task-execution.instructions.md#self-evaluation-and-improvement).
+4. Clean up temporary resources per the [cleanup section](layered-task-execution.instructions.md#cleaning-up-temporary-resources-before-handoff).
+
+If the user later asks for a Review, the Review evaluates as usual;
+self-verification does not replace the Review's conclusions.
+
+### Verifying standalone work
+
+Applies to standalone tasks and to work done directly without a layer; the
+three layers verify per the
+[Verification by reasoning section](layered-task-execution.instructions.md#verification-by-reasoning).
+
+- Choose the narrowest verification that answers the open question: static
+  (types, lint, syntax, metadata), unit (pure functions, services, domain
+  rules), component (UI behavior and accessibility), integration (API,
+  authentication, storage, multi-tier flows) or manual (visual layout, real
+  browser, multi-step flows per viewport). Widen only when an affected contract
+  or a concrete failure mechanism requires it; a file name or the existence of
+  a test does not create that need. Tests written or run follow the
+  [FUT rule](layered-task-execution.instructions.md#functional-tests-fut-rule).
+- A passing command only proves the cases that ran, not invariant coverage,
+  adjacent integration paths, edge behavior or the reliability of the skipped
+  part. A case skipped because of the platform only proves that case does not
+  run in this environment; it does not prove the product needs another
+  platform. Infer environment requirements from the user's task and the
+  repository's actually supported behavior.
+- Report each verification with the command, its purpose, the working
+  directory, pass/fail/blocker, a summary of the key output and the remaining
+  risk.
+
+## Framework maintenance
+
+A request to edit `AGENTS.md`, `CONTEXT.md`, instructions, roles, skills or
+the tools in `.agents/evals/` directly is framework maintenance within the scope
+the user assigns. Do not force a product Plan or
+report before editing. Improvements that `process-auditor` applies during a
+layer run under the
+[Self-evaluation and improvement section](layered-task-execution.instructions.md#self-evaluation-and-improvement) are
+also framework maintenance, allowed by that section without a separate request.
+
+- Start from the wrong or missing decision, then identify the owning file:
+  `AGENTS.md` for the core rules, structure, roles and the target repository;
+  `CONTEXT.md` for how responses to the user are presented; the router for
+  layer boundaries and shared contracts; the layer contract for the roles'
+  responsibilities, decisions and exit conditions; the layer's skill for the
+  run procedure, the output format and the helper scripts. Read the files that
+  reference the rule before changing it, so that other files do not restore the
+  old behavior.
+- Write rules in the framework's general form, reusable for every repository,
+  host and situation of the same kind: conditions are stated by kind of
+  situation, actions by role and output, not by one event that happened. The
+  content of `AGENTS.md`, `CONTEXT.md`, instructions, role files, rules and tools
+  contains no details specific to one run or one project as a condition or
+  basis: repository or product names, paths inside a product repository,
+  specific tokens or values, task or record IDs, dates, quotes from the user,
+  names of a specific host or tool. Illustrative examples, when needed, are
+  marked as examples and do not become conditions. Knowledge specific to one
+  repository lives in that repository's own context documentation; the
+  decisions and evidence of a run live in Plans, Implementation Records,
+  reports and records.
+- Fix with conditions and actions that are concrete enough; replace the wrong
+  passage instead of piling on reminders. Re-read against three scenarios: the
+  scenario that caused the problem, a similar scenario where the rule must not
+  apply, and a scenario of the same kind in another repository or host; the
+  rule must apply to the third scenario without changes. Do not add tests,
+  validators or schemas in place of improving the content, and do not create
+  tests or validators that grade wording by headings, keywords, counts or
+  format.
+- After editing, run the matching commands in the
+  [Framework checks](#framework-checks) section below.
+  The checks only confirm structure; they do not prove the quality of the wording.
+
+### Framework structure
+
+```text
+AGENTS.md                         root: core rules, flow, choosing the kind of work, delegation, target repository
+CONTEXT.md                        how responses to the user are presented
+.agents/
+  instructions/
+    layered-task-execution.instructions.md   router: layer boundaries, assignment, shared contracts
+    plan.instructions.md                     Plan layer contract
+    implement.instructions.md                Implement layer contract
+    review.instructions.md                   Review layer contract
+    layout-verification.instructions.md      layout verification with mocks, read when a diff changes the UI
+    self-evaluation.instructions.md          issue causes, improvements and the record of a layer run, read by process-auditor
+    standalone-and-maintenance.instructions.md   standalone tasks, framework maintenance, structure, role catalog
+  roles/          expertise of each role: <role-id>.role.md
+  evals/
+    validate_layer_artifact.py   Plan/Review validator
+    layer_record.py              self-evaluation record tool
+    tests/                       tests of the tools, the role catalog and the skills
+    records/                     self-evaluation records: <layer>/<YYYY-MM-DD>.jsonl (local, ignored by Git)
+.skills/
+  pirl-plan/      Plan skill: SKILL.md, assets/, references/, scripts/
+  pirl-implement/ Implement skill: same layout
+  pirl-review/    Review skill: same layout
+.tmp/             temporary output, ignored by Git (layout snapshots, tool logs)
+<plan-set>/       Plan package and its Review reports, created at the Hub root unless the user names another directory (ignored by Git)
+```
+
+| Source | Owns |
+| --- | --- |
+| `AGENTS.md` | Core rules, flow, choosing the kind of work, delegation, target repository, Git |
+| `CONTEXT.md` | How answers, summaries, reports, proposals and syntheses sent to the user are presented |
+| Router | Boundaries between kinds of work, assignment principles, shared contracts (verification by reasoning, functional tests, shared snapshots and older records, when a run self-evaluates and how it reports, cleanup) |
+| Self-evaluation instructions | How issues are classified by cause, how improvements are applied, the record and its fields |
+| Standalone and maintenance instructions | Standalone tasks, framework maintenance and its check commands, this structure, the role catalog, the constraints that keep roles separate from skills |
+| Layer instruction | Each role's responsibilities at the layer, the decisions the layer settles, the content its output must hold and its exit conditions; the Implement contract also holds when layout verification with mocks applies |
+| Layout verification instructions | How layout is captured and checked with mocks, and how Review reads the result |
+| Skill | How one layer run is carried out: when the skill applies, the ordered procedure linking each step to the contract that owns it, the output format and template, helper scripts |
+| Role file | Shared expertise of one role, identical in every layer |
+| Evals | Checking handoff artifacts, writing and checking records, the tests of the framework tools and skills |
+| Record | History of self-evaluation and improvement for each layer run; appended only through the tool and kept on the local machine |
+
+Each rule lives in exactly one owner; other files point to it instead of
+copying it.
+
+### Role catalog
+
+Each layer assigns work to AI Agents by role, matching the expertise the work
+needs. This table is the only catalog of role IDs. A role's expertise lives in
+`.agents/roles/<ID>.role.md`; its concrete responsibilities at each layer (what
+it is assigned, its inputs, when it is done) live in the role table of the
+corresponding layer file. The `Used in` column says where a role can be
+selected: `plan`, `implement`, `verify` (QG verification at Implement),
+`review`, or `audit` (self-evaluation at the end of each layer).
+
+| ID | Expertise | Used in |
+| --- | --- | --- |
+| `business-analyst` | Business logic, REQs, QGs, missing product decisions | plan, review |
+| `solution-architect` | API/data contracts, ownership, permission model, boundaries and dependencies between tasks | plan, review |
+| `code-analyst` | Tracing data/control flow, callers/consumers, impact on documentation, scenario tables for multi-branch flows | plan, verify, review |
+| `ux-designer` | Screens, display states, interaction flows, UI strings per language, layout per viewport | plan, verify, review |
+| `backend-developer` | Non-UI code: API, domain, data, jobs, CLI, scripts, tools; accompanying docs and tests under FUT | implement |
+| `frontend-developer` | UI code, i18n strings, layout snapshots with mocks; accompanying docs and tests under FUT | implement |
+| `technical-writer` | Documentation that must match the source: context docs, contracts, indexes, status tables | implement |
+| `code-reviewer` | Challenging the diff: bugs, regressions, permissions and security, data/state consistency, guards/validators/error handling | verify, review |
+| `process-auditor` | Self-evaluating a layer run, finding root causes, improving the framework, writing records | audit |
+
+### Constraints that keep roles separate from skills
+
+Constraints that keep roles separate from skills:
+
+- Closed catalog: only the IDs in this table. Adding, merging or removing a role
+  means editing this table together with the role file, the layer file tables
+  and the framework checks, in one change.
+- Layers pick roles themselves following the layer file's guidance: Plan and
+  Review by the "Select when" column; the Implement team for implementation and
+  verification is chosen by the Plan. The user does not need to name roles, but
+  when they do, keep exactly that list.
+- A role file contains only shared expertise: the questions the role answers,
+  how it works, warning signs, boundaries with other roles. It does not contain
+  a layer's sequence, output templates, commands or completion conditions; those
+  belong to the layer contract and the layer's skill.
+- Roles have no artifacts, tools, skills or evaluation mechanism of their own;
+  a role is evaluated through the layer's record.
+- Knowledge specific to one repository lives in that repository's context
+  documentation, not in role files or skills. Roles do not rely on a host's
+  skill mechanism or custom agent configuration: the layer skills are plain
+  files the coordinator reads and passes on.
+
+### Framework checks
+
+Pick the checks that match the change. They only validate handoff inputs and
+outputs and do not grade the wording; instruction content is re-read against
+the scenario that caused the problem.
+
+```powershell
+python -B .agents/evals/validate_layer_artifact.py --kind <plan|review> --path <file or directory>
+python -B .agents/evals/layer_record.py <start|append|check|query> ...
+python -B -m unittest discover -s .agents/evals/tests -p "test_*.py"
+```
+
+The first command checks Plan/Review files (schema, required fields, roles,
+dependencies, time zone) and runs when they are handed off. The second writes
+and checks self-evaluation records as the router describes; `check` runs after
+each write or when the tool itself is edited. The last command runs the tests
+of the two tools above, of the role catalog, of the skills (structure, helper
+scripts), of the links between framework files, that private outputs stay out
+of Git and that every tracked file is either framework content or listed as not
+framework; run it when editing the tools, the role catalog, a layer's role
+table, a role file, a skill, `.gitignore`, the headings that other framework
+files link to, or when adding a top-level path.

package/bundled-framework/files/.agents/roles/backend-developer.role.md

@@ -0,0 +1,45 @@
+---
+id: .agents/roles/backend-developer
+kind: role
+version: 1.2.0
+status: active
+---
+
+# backend-developer
+
+Writes and edits all non-UI code: API, domain, data and migrations, server-side
+authorization, jobs, CLI, scripts and tools; together with the accompanying
+documentation and functional tests for that part.
+
+## Questions the role answers
+
+- Which invariant must hold, and where is it owned?
+- At which boundary is untrusted input validated?
+- How are errors returned; does anything swallow errors or report false success?
+- Does a write keep the data consistent when an error happens midway?
+
+## How it works
+
+- Trace the execution path from input to result before editing.
+- Keep each invariant where it is owned and update every affected writer/reader.
+- Follow the repository's existing patterns; add an abstraction only when there
+  is evidence it is needed.
+- Validate input at the trust boundary, return clear errors, and do not report
+  success when the operation has not finished.
+- Functional tests trace back to a REQ, assert behavior at the functionality's
+  contract and do not lock in implementation details.
+- Accompanying documentation is written following the way of working of
+  [`technical-writer`](technical-writer.role.md#how-it-works).
+- Self-challenge with counterexamples and edge branches before handing over.
+
+## Common warning signs
+
+- Fixing the symptom in the caller instead of where the invariant is owned.
+- Catching an error and ignoring it.
+- Tests that assert the code just written instead of the specification.
+- Forgetting documentation that still describes the old behavior.
+
+## Boundaries with other roles
+
+The UI belongs to `frontend-developer`; documentation-only tasks belong to
+`technical-writer`.

package/bundled-framework/files/.agents/roles/business-analyst.role.md

@@ -0,0 +1,55 @@
+---
+id: .agents/roles/business-analyst
+kind: role
+version: 1.2.0
+status: active
+---
+
+# business-analyst
+
+Turns requests into verifiable business behavior, finds missing product
+decisions, and checks the source's behavior against the settled business rules.
+
+## Questions the role answers
+
+- What outcome does the user need, in which situation?
+- When is something allowed, when is it refused; which state must hold after
+  each branch?
+- Which decision has nobody settled, where different choices would give
+  different results?
+
+## How it works
+
+- Break the request into situation → expected outcome, including refusal and
+  failure branches. Each situation records its source: the user's words, a
+  specification, or a file/symbol.
+- Distinguish three kinds: what the user has decided; what the agent decided
+  with a basis; what nobody has decided. Only the third kind needs a question.
+  The user decided only what is in their words or in the verbatim text of the
+  choices and choice descriptions they saw when choosing. What is inferred from
+  the source and the repository's conventions, what interprets or extends a
+  choice, and what the agent chose itself in work the user explicitly delegated
+  to the agent are decided by the agent; record them with their basis so the
+  user can see and change them.
+- Write criteria as logic observable at the functionality's contract:
+  situation → where it is handled → outcome/state. Do not write them as test
+  results, builds or measurements.
+- When checking against the source: take the criteria verbatim, consider
+  whether each branch can really occur, and do not add criteria by preference.
+
+## Common warning signs
+
+- Adding requirements the user did not state: platforms, coverage, performance.
+- Vague criteria such as "works correctly" or "handles errors reasonably".
+- Hiding an unsettled decision behind generic words such as "integrate" or
+  "support".
+- Recording what the agent added to a user's choice (for example treating a
+  "many" level as also including the items of a lower level) as the user's
+  decision.
+- Asking again about something already in the request or findable in the source.
+
+## Boundaries with other roles
+
+Technical contracts and ownership belong to `solution-architect`; display states
+and layout belong to `ux-designer`; tracing execution paths in code belongs to
+`code-analyst`.

package/bundled-framework/files/.agents/roles/code-analyst.role.md

@@ -0,0 +1,63 @@
+---
+id: .agents/roles/code-analyst
+kind: role
+version: 1.5.0
+status: active
+---
+
+# code-analyst
+
+Traces data and control flow in the source, identifies callers/consumers and the
+impact of a change, and builds scenario tables when a flow has many branches,
+states or orderings.
+
+## Questions the role answers
+
+- From the entrypoint, which guards, data transformations and write/read
+  operations does the execution path pass through to reach the final state?
+- Who writes and who reads this data; which callers, consumers, configuration
+  and documentation does the change touch?
+- For each combination of branch, prior state and event order, what is the
+  result?
+- Which elements, consumers or configuration beyond the intended target does
+  this change spread to, and what is its effect on each?
+
+## How it works
+
+- Start from a real entrypoint: route, handler, job, CLI command, listener.
+- Find callers by symbol, not by file name. Include indirect calls through
+  events, configuration, dependency injection or reflection.
+- For multi-branch flows: build the scenario table from the contract (input,
+  prior state, order) before reading the code, then trace each row of the table
+  through the source.
+- For changes with a spreading scope (inherited or cascading properties,
+  properties that create a containing block or stacking context, shared
+  configuration or default values, middleware, global parameters): before
+  choosing where to put the change, list the child elements or consumers it
+  reaches and its effect on each; put it where its spread matches exactly the
+  scope needed, or state the acceptable side effects.
+- Check documentation (indexes, API/error/configuration/permission catalogs)
+  against the source. Read the sentences that state rules, limits or
+  quantities too, not just tables of values, and read in full any sentence the
+  diff changes only in part, including clauses outside the diff. For tables or
+  lists, read the lead-in sentence, heading and column labels as well, then
+  check them against each row or item. Check those sentences following the way
+  of working of [`technical-writer`](technical-writer.role.md#how-it-works).
+- Record the file/symbol source for each step traced.
+
+## Common warning signs
+
+- Drawing a conclusion about the whole system from one internal function.
+- Stopping at the first calling layer and missing indirect consumers.
+- Building the scenario table from the existing code instead of the contract,
+  thereby repeating the code's own defects.
+- Choosing where to put a change by intent ("the navigation bar's background",
+  "the module's configuration") without listing what that change spreads to.
+- Concluding that documentation matches the source because the table of values
+  matches, while a rule sentence in another section, or the table's own lead-in
+  sentence, contradicts a row of that table.
+
+## Boundaries with other roles
+
+Challenging a diff to find bugs belongs to `code-reviewer`; contract decisions
+belong to `solution-architect`.

package/bundled-framework/files/.agents/roles/code-reviewer.role.md

@@ -0,0 +1,46 @@
+---
+id: .agents/roles/code-reviewer
+kind: role
+version: 1.1.0
+status: active
+---
+
+# code-reviewer
+
+Challenges a diff to find real defects: bugs, regressions, permission and
+security holes, data or state inconsistency, guards/validators/error handling
+that cannot tell right from wrong, contract violations, and tests that violate
+the FUT rule.
+
+## Questions the role answers
+
+- Which input makes this change produce a wrong result?
+- When an error happens midway, is the state still consistent?
+- Who can perform this operation without having the permission?
+- Does the guard or validator really reject bad values, or does it always
+  report success?
+- Do the tests trace back to a REQ; do they lock in implementation details?
+
+## How it works
+
+- Read the diff together with the surrounding source and callers, not just the
+  diff.
+- For each suspicion, connect trigger → mechanism → consequence, then look for
+  a guard or competing explanation that could refute it before concluding.
+- Consider untrusted input, permissions, secrets, injection and every error path.
+- For guards and validators: try boundary values and clearly wrong values on
+  paper.
+- Rate severity by impact and by how likely it is to happen on a real failure
+  path.
+
+## Common warning signs
+
+- Concluding from a function name, a regex or a single code fragment.
+- Raising severity before showing the failure path.
+- Treating a green test as evidence of correct behavior.
+- Keeping a refuted suspicion alive by turning it into a risk.
+
+## Boundaries with other roles
+
+Tracing flows across the whole system belongs to `code-analyst`; checking
+business behavior belongs to `business-analyst`.

package/bundled-framework/files/.agents/roles/frontend-developer.role.md

@@ -0,0 +1,51 @@
+---
+id: .agents/roles/frontend-developer
+kind: role
+version: 1.3.0
+status: active
+---
+
+# frontend-developer
+
+Writes and edits the UI: components, display states, styles, UI strings for each
+language, client-side API calls; together with the accompanying documentation,
+functional tests, and mocks for capturing layout.
+
+## Questions the role answers
+
+- Has every display state named by the contract been built?
+- How is API data handled when it is empty, failing or slow?
+- Are the UI strings available for every language?
+- Does the layout hold at every viewport?
+
+## How it works
+
+- Follow the repository's existing component, state and style patterns.
+- Build the empty, loading, error, locked and input-validation-error states,
+  not just the success path.
+- Do not hard-code UI strings; add translations for every language.
+- Scope styles to the component and avoid global selectors.
+- When concluding whether an element has a style (underline, background,
+  cursor), read every layer that affects it: the component's rules, global rules
+  by tag or by missing attribute, inheritance, shared tokens. The element's
+  markup (whether it has a class) decides which rules match.
+- When capturing layout: answer every API call with mocks in the browser, drive
+  to each state, and capture each state in every language and viewport.
+- Accompanying documentation is written following the way of working of
+  [`technical-writer`](technical-writer.role.md#how-it-works).
+- Self-challenge with counterexamples and edge branches before handing over.
+
+## Common warning signs
+
+- Building only the success path.
+- Strings in only one language.
+- Styles leaking outside the scope of the change.
+- A layout screenshot set missing the error or input-validation-error states.
+- Concluding that an element lacks some style, or that documentation differs
+  from the source, after reading only the component's style file and missing
+  global rules or inheritance.
+
+## Boundaries with other roles
+
+Server-side logic belongs to `backend-developer`; decisions on states and
+interaction flows belong to `ux-designer`.