pirl-framework-cli 0.0.0-stage → 1.0.0

package/bundled-framework/files/README.md

@@ -0,0 +1,170 @@
+# PIRL Framework
+
+**Plan – Implement – Review Layer**: a Hub that coordinates software development
+work for AI Agents, running entirely on instruction files.
+
+You assign work in plain words. The Agent reads [`AGENTS.md`](AGENTS.md), picks
+the right layer, splits the work among specialist roles, records the results as
+files in the repository, then improves the instruction files themselves after
+each run.
+
+## What the framework does
+
+- **Three layers, three skills.** Plan settles the work to do and the quality
+  gates (QG). Implement edits the source according to the Plan. Review checks
+  the result against the QGs by reasoning on the source. Each layer is run
+  through its skill in `.skills/` (`pirl-plan`, `pirl-implement`, `pirl-review`).
+- **Any repository.** The product repositories are not part of the Hub. You
+  name the target repository of each request; the Agent reads that
+  repository's own context documentation (its `AGENTS.md`, `CLAUDE.md`, README
+  and similar).
+- **AI Agent roles.** Each layer assigns work to roles with the right expertise,
+  for example `business-analyst`, `backend-developer`, `code-reviewer`.
+- **Self-improvement.** At the end of each layer run, the `process-auditor` role
+  finds each role's mistakes, fixes the relevant instruction files at the root,
+  writes a JSONL record and reports what was fixed and where.
+
+The framework does not build, does not run the application for acceptance and
+does not deploy. Those belong to your build/test/release stage. Implement only
+writes and runs functional tests related to the request, and captures layout
+with mocks when the UI changes.
+
+## Requirements
+
+- An AI Agent that can read files in the repository and run commands, for
+  example Claude Code. If the host loads `AGENTS.md` automatically, it works
+  right away; if not, ask the Agent to read `AGENTS.md` before assigning work.
+- Git.
+- Python 3.9 or later, for the validator, the record tool and the skills' scripts.
+
+## Quick start
+
+### 1. Get the Hub
+
+```powershell
+git clone https://github.com/tdmadc107/PIRL-framework.git
+```
+
+### 2. Have a target repository ready
+
+Any local Git repository works; nothing needs registering. Give its path in your
+request, relative to the Hub root or absolute. If you want to keep clones
+inside the Hub, put them in `.repos/`, which Git ignores.
+
+The Agent learns the repository from the repository itself: architecture,
+conventions, the command that runs tests by file or name, UI languages and
+viewports, known gaps. If the repository has no such document yet, you can
+assign the Agent to write one (for example its `AGENTS.md`) as a standalone
+task.
+
+### 3. Assign work
+
+No special commands or keywords are needed; just say it:
+
+| You want to | Example request | The Agent runs |
+| --- | --- | --- |
+| Plan | "Create a Plan for `../shop-web`: customers get an email when an order is cancelled" | `pirl-plan` skill |
+| Implement | "Implement Plan T01 in `<package>`" | `pirl-implement` skill |
+| Review | "Review the implementation of Plan T01" | `pirl-review` skill |
+| Fix per a Review | "Fix per report `<report path>`" | `pirl-implement` skill, repair run |
+| Small work outside the chain | "Update the AGENTS.md of shop-web" | Standalone task |
+| Edit the framework itself | "Fix the cleanup rule in the router" | Framework maintenance |
+| Just ask | "Which tasks does Plan T01 depend on?" | Answer, no files created |
+
+Each layer runs only when you ask for it; the Agent does not move on to the next
+layer by itself. The Agent picks the smallest team of roles with enough
+expertise. To choose the team yourself, name the roles in your request; the role
+catalog is in the [standalone and maintenance instructions](.agents/instructions/standalone-and-maintenance.instructions.md#role-catalog).
+
+Plans and reports go where you say. If you name no location, they are created
+under the Hub root. Inside the Hub, Git ignores Plan packages and their reports
+(directories named `<request-slug>_<YYYYMMDD-HHmmss>/`), because they describe
+your projects.
+
+## A full working cycle
+
+1. **Plan.** The Agent investigates the source and asks when a product decision
+   is missing. The result is a Plan package `<request-slug>_<YYYYMMDD-HHmmss>/`,
+   one file per task with: What to do (REQs), How to do it, Participating roles,
+   Required quality gates (QGs). Read and settle the Plan before implementing.
+2. **Implement.** The Agent edits the source in the target repository, within
+   the Plan's scope. Verification roles conclude each QG by reasoning on the
+   source. The results go into the `Implementation Record` section at the end of
+   the Plan file. When the UI changes, layout screenshots are in
+   `.tmp/layout-snapshots/` (not in git).
+3. **Review.** The Agent checks each QG against the source and writes a report
+   `<plan-set>/<task>/round-<NN>-review-...md`; with the default location it
+   sits inside the Plan package. The report has two sections: `Business` (a
+   PASS, FAIL or BLOCKED conclusion with FINDs, RISKs and BLOCKs) and
+   `Evaluations` (an assessment of each role of the Implement run).
+4. **Fix.** When Business is FAIL, assign "Fix per report ...". Implement runs a
+   repair run with the team named in the report, then you ask for a new Review
+   round.
+5. **Commit.** The Agent commits or pushes only when you ask. Changes in the
+   target repository are committed in that repository; a Hub commit carries the
+   framework improvements of the same run. Plans, reports and records stay on
+   your machine.
+
+## Reading the self-improvement part after each run
+
+At the end of each Plan, Implement or Review run, the Agent's response has:
+
+- **Self-improvement:** the record ID, and for each applied improvement: the
+  issue, cause, file and section edited, old → new version. Look at the diff of
+  these files before committing.
+- **Needs confirmation:** the closing block of the answer; it has a point about
+  this improvement only when the improvement would loosen a safety rule. You
+  choose to apply, skip, or have it re-evaluated by a separate agent; the
+  details of the issue and the change are in the "Self-improvement" section.
+  The evaluation is always delegated to a separate agent; only when the host
+  cannot create agents does the Agent evaluate itself and state the reason.
+
+Safety rules (commit, push, secrets, destructive actions, points that need your
+decision) are never loosened by self-improvement without your consent. The full
+definition is in [`AGENTS.md`](AGENTS.md#safety-rules-and-self-improvement).
+
+Records live in `.agents/evals/records/<layer>/<YYYY-MM-DD>.jsonl`. They
+describe your projects, so Git ignores that directory: records stay on your
+machine and the tool still reads them. To look up history:
+
+```powershell
+python -B .agents/evals/layer_record.py query --issue-key <issue key>
+python -B .agents/evals/layer_record.py query --layer review --plan-set <package> --task T01
+python -B .agents/evals/layer_record.py check
+```
+
+## Checks after editing the framework
+
+```powershell
+python -B -m unittest discover -s .agents/evals/tests -p "test_*.py"
+```
+
+Pick the check commands that match what you edited: see
+[Framework checks](.agents/instructions/standalone-and-maintenance.instructions.md#framework-checks).
+
+## Directory 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/         layer instructions, roles, evals (validator, record tool, tests, local records)
+.skills/         the pirl-plan, pirl-implement and pirl-review skills
+.tmp/            temporary output, not in git
+```
+
+Full tree: [framework structure](.agents/instructions/standalone-and-maintenance.instructions.md#framework-structure).
+
+## Reference documentation
+
+| To learn about | Read |
+| --- | --- |
+| Core rules, flow, delegation, target repository | [`AGENTS.md`](AGENTS.md) |
+| How the Agent presents answers, summaries, proposals | [`CONTEXT.md`](CONTEXT.md) |
+| Choosing a layer, shared contracts, functional tests, self-improvement | [Router](.agents/instructions/layered-task-execution.instructions.md) |
+| Each layer's decisions | [Plan](.agents/instructions/plan.instructions.md), [Implement](.agents/instructions/implement.instructions.md), [Review](.agents/instructions/review.instructions.md) |
+| Running each layer, file formats, templates | [`pirl-plan`](.skills/pirl-plan/SKILL.md), [`pirl-implement`](.skills/pirl-implement/SKILL.md), [`pirl-review`](.skills/pirl-review/SKILL.md) |
+| Each role's expertise | [`.agents/roles/`](.agents/roles/) |
+
+## License
+
+[MIT](LICENSE).

package/bundled-framework/files/gitignore.pirl-bundled

@@ -0,0 +1,12 @@
+.tmp/
+__pycache__/
+*.stackdump
+
+# External local tools: kept on the local machine, not part of the framework.
+.tools/
+
+# Private data about the user's projects: kept on the local machine, never committed.
+.agents/evals/records/
+.repos/
+# Plan packages <request-slug>_<YYYYMMDD-HHmmss>/ and the Review reports inside them, anywhere in the Hub.
+*_[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]/

package/bundled-framework/manifest.json

@@ -0,0 +1,45 @@
+{
+  "version": "1.1.0",
+  "digest": "7826b2333a1d935560c750991fff036ffaa9b204",
+  "files": {
+    ".agents/evals/layer_record.py": "e9dc56cf38b3723aed3c3f22a2a8c0d0c3dfa32c",
+    ".agents/evals/tests/test_layer_record.py": "ed6bca11e9103c6be9a1436bc764a2fd14639e75",
+    ".agents/evals/tests/test_skills.py": "43ae9a91adc7a338f3609e32edffa8ae2d39ed3f",
+    ".agents/evals/tests/test_validate_layer_artifact.py": "013445c684ebc38dfbba919fb234a1a8984c1213",
+    ".agents/evals/validate_layer_artifact.py": "cef4fe2a85a983828f201a5ff9ce74e448a1bfc7",
+    ".agents/instructions/implement.instructions.md": "d168b1c2d0d229047561327091bc143a65924744",
+    ".agents/instructions/layered-task-execution.instructions.md": "bebc5f25f6b0b409a1054b43f8d8ede2f6df9b24",
+    ".agents/instructions/layout-verification.instructions.md": "746abd0793ec096c2d69501e00a16b3b6433aad4",
+    ".agents/instructions/plan.instructions.md": "59358acd397653f71a5f15bc1c2be0ccdf6045c9",
+    ".agents/instructions/review.instructions.md": "ba0fd8a558d5c44947189f17e4d430c1a3eb0982",
+    ".agents/instructions/self-evaluation.instructions.md": "280c5ec812fd61ed31809037dfcd2d593cc47c1a",
+    ".agents/instructions/standalone-and-maintenance.instructions.md": "15a96334813b1d74f824118c70a18f0b6712dbef",
+    ".agents/roles/backend-developer.role.md": "b41ae3aa5f930369f995293dabce797b58cc3688",
+    ".agents/roles/business-analyst.role.md": "6552002bff81ca4da70da9d05145c49154f23fcf",
+    ".agents/roles/code-analyst.role.md": "d171fb0388ef2b564d6994baaa0ca9b450686121",
+    ".agents/roles/code-reviewer.role.md": "8f7053eff48ac246cef36bd9fa6dab03eca88f4d",
+    ".agents/roles/frontend-developer.role.md": "5feffc5035281e787c2d1f6b4bf53adc017b5601",
+    ".agents/roles/process-auditor.role.md": "896f30f77a4d07d31258f13d65e81e867914a30e",
+    ".agents/roles/solution-architect.role.md": "48855ae414d3af4ca8bf42f99cbd8ad5d5e73da5",
+    ".agents/roles/technical-writer.role.md": "aff96083ffe43a11395b1277c208aa991b74bdd3",
+    ".agents/roles/ux-designer.role.md": "349268f8817a36facf4a854daaa571d3fb62022d",
+    ".gitignore": "9e417338f1bd7356a16e4e9de85ee6b3ceadc315",
+    ".skills/pirl-implement/SKILL.md": "da0931090bc11292fa41c0122c31cf4749d80d5c",
+    ".skills/pirl-implement/assets/implementation-record-template.md": "66bfc2333f1bcf7a8b4dd3394f2ebb8a960cfccd",
+    ".skills/pirl-implement/references/implementation-record-format.md": "bad5b435a8ac4ed28a9d9c933549cb413ad2bfdc",
+    ".skills/pirl-implement/scripts/add_implementation_record.py": "43a5dcdefd24c9dcac4930a26fb842dea1ed9ded",
+    ".skills/pirl-implement/scripts/new_layout_run.py": "fbfd0f44b09200b4d7718aed5953680cc7ea45a3",
+    ".skills/pirl-plan/SKILL.md": "27b4903bfb12418c465e0b45f9b70e740ae7b1e2",
+    ".skills/pirl-plan/assets/plan-template.md": "560bf8b8dca37d1b203b2c4cd643007c688dc10e",
+    ".skills/pirl-plan/references/plan-format.md": "53d518428920b332b6678310105d3c3a48979f0d",
+    ".skills/pirl-plan/scripts/new_plan.py": "ac949673d7c7a779200009dae2992d25381b8e5d",
+    ".skills/pirl-review/SKILL.md": "35c8308aa6e4c18047953ccad5ff41172461d943",
+    ".skills/pirl-review/assets/review-template.md": "1f27f7082d01c8eb4de94f9693913baf7aad64a2",
+    ".skills/pirl-review/references/review-format.md": "5a24c923a7d517bd4d1f42d0dd5907aac81a72a9",
+    ".skills/pirl-review/scripts/new_review.py": "27150e6a6e249507c839a05a7f337380a062b1c1",
+    "AGENTS.md": "ba49644c3d519843cd7dc97d6d8a52ca8bd5d23e",
+    "CONTEXT.md": "2779b5131d1ff7e8963c2516709d1a40c341823e",
+    "LICENSE": "f5a48e5836ce6a46ffcf13a8240a954b244b90ae",
+    "README.md": "d53ba7374742fae5e519bbc7953878ad858f7ca6"
+  }
+}

package/dist/bin/main.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { join } from 'node:path';
+import { render } from 'ink';
+import { createClipboard } from '../core/clipboard.js';
+import { loadConfig, saveConfig } from '../core/config.js';
+import { exec } from '../core/exec.js';
+import { configFile, displayPath, hubDir, packageInfo, packageRoot, pirlHome } from '../core/paths.js';
+import { detectTargetRepo } from '../core/targetRepo.js';
+import { runDoctor } from '../doctor/doctor.js';
+import { readClaudeQuota } from '../engine/claudeQuota.js';
+import { attachmentContext, pathIndex, resolveMentions } from '../engine/attachments.js';
+import { createClaudeRunner } from '../engine/claudeRunner.js';
+import { readPlanPackages, readRecords } from '../engine/hubData.js';
+import { RunController } from '../engine/run.js';
+import { listRuns, saveRun } from '../engine/runStore.js';
+import { loadBundledFramework } from '../hub/framework.js';
+import { frameworkServices } from '../hub/services.js';
+import { ensureHub } from '../hub/hub.js';
+import { getProvider } from '../providers/index.js';
+import { App } from '../ui/App.js';
+import { MOUSE_OFF, mouseSequence } from '../ui/terminalInput.js';
+/** The run's model settings as the provider's arguments; `default` and `inherit` leave the choice to it. */
+export const runModels = (config) => ({
+    model: config.model === 'default' ? undefined : config.model,
+    roleModel: config.roleModel === 'inherit' ? undefined : config.roleModel,
+    effort: config.effort === 'default' ? undefined : config.effort,
+});
+const HELP = `PIRL CLI: chạy PIRL framework (Plan – Implement – Review) bằng agent CLI bạn đã đăng nhập.
+
+Cách dùng
+  pirl              Mở TUI. Thư mục hiện tại (git repo) là target repo.
+  pirl --version    In phiên bản CLI và framework đi kèm.
+  pirl --help       In hướng dẫn này.
+
+Trong TUI, gõ / để xem lệnh, hoặc /help để xem lệnh và phím tắt.`;
+async function main() {
+    const root = packageRoot();
+    const pkg = packageInfo(root);
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(HELP);
+        return 0;
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        let framework = 'không có';
+        try {
+            framework = `fw-${loadBundledFramework(root).manifest.version}`;
+        }
+        catch { }
+        console.log(`pirl ${pkg.version} (framework ${framework})`);
+        return 0;
+    }
+    if (args.length > 0) {
+        console.error(`pirl: không nhận tham số "${args[0]}". Lệnh chạy bên trong TUI.\n\n${HELP}`);
+        return 2;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error('pirl cần chạy trong một terminal tương tác.');
+        return 1;
+    }
+    const home = pirlHome();
+    const notes = [];
+    const { config, warning } = loadConfig(configFile(home));
+    if (warning)
+        notes.push({ tone: 'warning', text: warning });
+    const target = await detectTargetRepo(process.cwd());
+    if (target.kind === 'none') {
+        notes.push({ tone: 'warning', text: `${target.reason}: các layer bị khoá.`, hint: 'Mở `pirl` trong thư mục của một git repo để dùng /pirl-plan, /pirl-implement, /pirl-review.' });
+    }
+    let bundle = null;
+    let hub = null;
+    let hubError = null;
+    try {
+        bundle = loadBundledFramework(root);
+        const result = await ensureHub(hubDir(home), bundle);
+        hub = result.status;
+        if (result.created)
+            notes.push({ tone: 'success', text: `Đã tạo Hub tại ${displayPath(hub.path)} với framework ${hub.upstreamTag ?? ''}.` });
+    }
+    catch (error) {
+        hubError = error instanceof Error ? error.message : String(error);
+        notes.push({ tone: 'error', text: `Không chuẩn bị được Hub: ${hubError}` });
+    }
+    const targetRoot = target.kind === 'git' ? target.root : null;
+    // `@` mentions are read from the target repository, or from the start directory outside one.
+    const attachBase = targetRoot ?? process.cwd();
+    const paths = cachedPaths(() => pathIndex(attachBase));
+    const runner = createClaudeRunner();
+    const instance = render(_jsx(App, { info: { cliVersion: pkg.version, target, hub, hubError }, initialConfig: config, startupNotes: notes, services: {
+            runDoctor: current => runDoctor({ exec, provider: getProvider(current.provider), target, hub, hubError }),
+            saveConfig: next => saveConfig(configFile(home), next),
+            startRun: options => new RunController({ runner, hub: hub.path, target: targetRoot, logDir: join(home, 'logs'), quota: () => readClaudeQuota('claude', hub.path), python: options.python, maxParallelRoles: options.config.maxParallelRoles, recentOutputs: options.recentOutputs, attachments: options.attachments, ...runModels(options.config) }, options.id, options.kind, options.request, options.resume),
+            saveRun: run => targetRoot && saveRun(home, targetRoot, run),
+            runs: () => (targetRoot ? listRuns(home, targetRoot) : []),
+            plans: () => (hub && targetRoot ? readPlanPackages(hub.path, targetRoot) : []),
+            records: () => (hub ? readRecords(hub.path, targetRoot) : []),
+            clipboard: createClipboard({ writeTerminal: data => process.stdout.write(data) }),
+            quota: () => (hub ? readClaudeQuota('claude', hub.path) : Promise.resolve(null)),
+            paths: () => paths.get(),
+            attach: text => attachmentContext(resolveMentions(text, attachBase, process.cwd()), [attachBase, ...(hub ? [hub.path] : [])]),
+            setMouse: mode => process.stdout.write(mouseSequence(mode)),
+            framework: hub && bundle ? frameworkServices(hub.path, bundle, runner, config => runModels(config).model) : undefined,
+        } }), 
+    // Ctrl+C is handled by the TUI: it stops a running run first. The kitty keyboard protocol, where the
+    // terminal supports it (Windows Terminal 1.25+, kitty, WezTerm, Ghostty, iTerm2), tells Shift+Enter from Enter.
+    // Incremental rendering rewrites only the rows that changed: a spinner tick sends a few bytes, not a screen.
+    { alternateScreen: true, exitOnCtrlC: false, kittyKeyboard: { mode: 'auto' }, incrementalRendering: true });
+    // The terminal keeps reporting the mouse after the TUI ends unless it is told to stop, even on a crash.
+    process.once('exit', () => process.stdout.write(MOUSE_OFF));
+    await instance.waitUntilExit();
+    process.stdout.write(MOUSE_OFF);
+    return 0;
+}
+main().then(code => process.exit(code), error => {
+    console.error(error instanceof Error ? error.stack : error);
+    process.exit(1);
+});
+/** The path index for `@` completion, read again when older than a few seconds so new files show up. */
+function cachedPaths(read, maxAgeMs = 10_000) {
+    let cached = null;
+    return {
+        get() {
+            if (!cached || Date.now() - cached.at > maxAgeMs)
+                cached = { at: Date.now(), value: read().catch(() => []) };
+            return cached.value;
+        },
+    };
+}

package/dist/bin/pirl.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// React and Ink run their development builds unless NODE_ENV says otherwise; the development build checks
+// every render and costs several times the CPU. Set it before they load, which is why the TUI is imported here.
+process.env.NODE_ENV ??= 'production';
+await import('./main.js');
+export {};

package/dist/commands/dispatch.js

@@ -0,0 +1,57 @@
+import { commandUsage } from './registry.js';
+const LAYERS = { 'pirl-plan': 'plan', 'pirl-implement': 'implement', 'pirl-review': 'review' };
+const LABELS = { plan: 'Plan', implement: 'Implement', review: 'Review' };
+export function dispatch(input, context) {
+    switch (input.kind) {
+        case 'empty':
+            return [];
+        case 'unknown-command':
+            return [{ type: 'note', tone: 'error', text: `Không có lệnh /${input.name}.`, hint: 'Gõ /help để xem danh sách lệnh.' }];
+        case 'text':
+            // The coordinator classifies free text (question, standalone task, framework maintenance) per AGENTS.md.
+            return [{ type: 'run', kind: 'chat', request: input.text }];
+        case 'command':
+            break;
+    }
+    const { spec, request } = input;
+    if (spec.name in LAYERS) {
+        const kind = LAYERS[spec.name];
+        if (context.target.kind !== 'git') {
+            return [
+                {
+                    type: 'note',
+                    tone: 'error',
+                    text: `Layer ${LABELS[kind]} bị khoá: ${context.target.reason.toLowerCase()}.`,
+                    hint: 'Thoát (/exit), chuyển tới thư mục của một git repo rồi gõ lại `pirl`.',
+                },
+            ];
+        }
+        if (!request)
+            return [{ type: 'note', tone: 'warning', text: 'Thiếu nội dung request.', hint: `Cú pháp: ${commandUsage(spec)}` }];
+        return [{ type: 'run', kind, request }];
+    }
+    switch (spec.name) {
+        case 'help':
+            return [{ type: 'overlay', overlay: 'help' }];
+        case 'doctor':
+            return [{ type: 'overlay', overlay: 'doctor' }, { type: 'doctor' }];
+        case 'settings':
+            return [{ type: 'overlay', overlay: 'settings' }];
+        case 'framework':
+            return [{ type: 'overlay', overlay: 'framework' }];
+        case 'plans':
+            return [{ type: 'overlay', overlay: 'plans' }];
+        case 'records':
+            return [{ type: 'overlay', overlay: 'records' }];
+        case 'resume':
+            return [{ type: 'resume' }];
+        case 'copy':
+            return [{ type: 'copy' }];
+        case 'clear':
+            return [{ type: 'clear' }];
+        case 'exit':
+            return [{ type: 'exit' }];
+        default:
+            return [];
+    }
+}

package/dist/commands/registry.js

@@ -0,0 +1,39 @@
+export const COMMANDS = [
+    { name: 'pirl-plan', group: 'Layer', summary: 'Tạo hoặc điều chỉnh Plan', takesRequest: true },
+    { name: 'pirl-implement', group: 'Layer', summary: 'Thực hiện một task của Plan, hoặc sửa theo report', takesRequest: true },
+    { name: 'pirl-review', group: 'Layer', summary: 'Review kết quả implement của một task', takesRequest: true },
+    { name: 'resume', group: 'Run', summary: 'Chạy tiếp run bị dừng', takesRequest: false },
+    { name: 'plans', group: 'Tra cứu', summary: 'Danh sách Plan, task, report của repo này', takesRequest: false },
+    { name: 'records', group: 'Tra cứu', summary: 'Tra cứu record tự cải tiến', takesRequest: false },
+    { name: 'settings', group: 'Cấu hình', summary: 'Provider, giao diện, số role chạy song song', takesRequest: false },
+    { name: 'doctor', group: 'Cấu hình', summary: 'Kiểm tra provider, Python, Git, Hub', takesRequest: false },
+    { name: 'framework', group: 'Framework', summary: 'Phiên bản framework, cải tiến cục bộ, cập nhật', takesRequest: false },
+    { name: 'copy', group: 'Phiên', summary: 'Copy câu trả lời gần nhất của PIRL', takesRequest: false },
+    { name: 'clear', group: 'Phiên', summary: 'Xoá khung chat, bắt đầu hội thoại mới', takesRequest: false },
+    { name: 'help', group: 'Phiên', summary: 'Danh sách lệnh và phím tắt', takesRequest: false },
+    { name: 'exit', group: 'Phiên', summary: 'Thoát PIRL', takesRequest: false },
+];
+export const commandUsage = (spec) => `/${spec.name}${spec.takesRequest ? ' <request>' : ''}`;
+export function parseInput(raw) {
+    const text = raw.trim();
+    if (!text)
+        return { kind: 'empty' };
+    if (!text.startsWith('/'))
+        return { kind: 'text', text };
+    const match = /^\/(\S*)\s*([\s\S]*)$/.exec(text);
+    const name = match[1].toLowerCase();
+    const spec = COMMANDS.find(command => command.name === name);
+    return spec ? { kind: 'command', spec, request: match[2].trim() } : { kind: 'unknown-command', name };
+}
+/**
+ * Commands offered while the user types a command name: input starting with "/" and no space yet.
+ * Prefix matches come first, then commands that contain the typed text elsewhere (so "/plan" finds /pirl-plan).
+ */
+export function suggestCommands(input) {
+    if (!input.startsWith('/') || /\s/.test(input))
+        return [];
+    const typed = input.slice(1).toLowerCase();
+    const prefix = COMMANDS.filter(command => command.name.startsWith(typed));
+    const inside = COMMANDS.filter(command => !command.name.startsWith(typed) && command.name.includes(typed));
+    return [...prefix, ...inside];
+}

package/dist/core/clipboard.js

@@ -0,0 +1,70 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { exec as defaultExec, succeeded } from './exec.js';
+const POWERSHELL_FLAGS = ['-NoProfile', '-NonInteractive', '-Command'];
+function tools(platform, env) {
+    const windows = platform === 'win32' || Boolean(env['WSL_DISTRO_NAME']);
+    if (windows) {
+        const powershell = platform === 'win32' ? 'powershell' : 'powershell.exe';
+        return {
+            windows,
+            copy: [{ command: powershell, args: POWERSHELL_FLAGS }],
+            paste: [{ command: powershell, args: [...POWERSHELL_FLAGS, '[Console]::OutputEncoding=[Text.Encoding]::UTF8; Get-Clipboard -Raw'] }],
+        };
+    }
+    if (platform === 'darwin')
+        return { windows, copy: [{ command: 'pbcopy', args: [] }], paste: [{ command: 'pbpaste', args: [] }] };
+    const wayland = env['WAYLAND_DISPLAY'] ? [{ copy: { command: 'wl-copy', args: [] }, paste: { command: 'wl-paste', args: ['--no-newline'] } }] : [];
+    const x11 = [
+        { copy: { command: 'xclip', args: ['-selection', 'clipboard'] }, paste: { command: 'xclip', args: ['-selection', 'clipboard', '-o'] } },
+        { copy: { command: 'xsel', args: ['--clipboard', '--input'] }, paste: { command: 'xsel', args: ['--clipboard', '--output'] } },
+    ];
+    const all = [...wayland, ...x11];
+    return { windows, copy: all.map(tool => tool.copy), paste: all.map(tool => tool.paste) };
+}
+/** OSC 52 asks the terminal itself to set the clipboard; Windows Terminal, iTerm2, kitty and others honor it. */
+export const osc52 = (text) => `\u001B]52;c;${Buffer.from(text, 'utf8').toString('base64')}\u0007`;
+export function createClipboard(options = {}) {
+    const exec = options.exec ?? defaultExec;
+    const env = options.env ?? process.env;
+    const found = tools(options.platform ?? process.platform, env);
+    const utf8Env = { ...env, LANG: env['LANG'] || 'en_US.UTF-8', LC_CTYPE: env['LC_CTYPE'] || 'en_US.UTF-8' };
+    return {
+        async copy(text) {
+            for (const tool of found.copy) {
+                let result;
+                if (found.windows) {
+                    const dir = mkdtempSync(join(tmpdir(), 'pirl-clip-'));
+                    const file = join(dir, 'clip.txt');
+                    try {
+                        writeFileSync(file, text, 'utf8');
+                        const quoted = file.replace(/'/g, "''");
+                        result = await exec(tool.command, [...tool.args, `Get-Content -Raw -Encoding UTF8 -LiteralPath '${quoted}' | Set-Clipboard`], { timeoutMs: 15_000 });
+                    }
+                    finally {
+                        rmSync(dir, { recursive: true, force: true });
+                    }
+                }
+                else {
+                    result = await exec(tool.command, tool.args, { input: text, env: utf8Env, timeoutMs: 15_000 });
+                }
+                if (succeeded(result))
+                    return 'native';
+            }
+            if (options.writeTerminal) {
+                options.writeTerminal(osc52(text));
+                return 'terminal';
+            }
+            return 'failed';
+        },
+        async paste() {
+            for (const tool of found.paste) {
+                const result = await exec(tool.command, tool.args, { env: utf8Env, timeoutMs: 15_000 });
+                if (succeeded(result))
+                    return found.windows ? result.stdout.replace(/\r\n/g, '\n').replace(/\n$/, '') : result.stdout;
+            }
+            return null;
+        },
+    };
+}

package/dist/core/config.js

@@ -0,0 +1,73 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const PROVIDER_IDS = ['claude', 'codex', 'gemini', 'copilot'];
+export const COLOR_SCHEME_IDS = ['pirl', 'ocean', 'forest', 'sunset', 'grape', 'mono'];
+/** Model aliases the provider resolves to its newest version; `default` leaves the choice to the provider. */
+export const MODEL_IDS = ['sonnet', 'opus', 'fable', 'haiku', 'default'];
+/** `inherit` runs the roles on the coordinator's model. */
+export const ROLE_MODEL_IDS = ['inherit', 'sonnet', 'opus', 'fable', 'haiku'];
+/**
+ * What the mouse does in the TUI:
+ * - `select`: the terminal keeps the mouse, so dragging selects text as usual; the wheel reaches the TUI as the
+ *   arrow keys (alternate scroll mode), which scroll the chat.
+ * - `wheel`: the TUI receives the wheel itself; selecting text then needs Shift held while dragging.
+ * - `off`: the TUI asks nothing of the mouse.
+ */
+export const MOUSE_IDS = ['select', 'wheel', 'off'];
+export const EFFORT_IDS = ['default', 'low', 'medium', 'high', 'xhigh', 'max'];
+export const DEFAULT_CONFIG = {
+    provider: 'claude',
+    theme: 'auto',
+    colors: 'pirl',
+    glyphs: 'auto',
+    motion: true,
+    mouse: 'select',
+    maxParallelRoles: 2,
+    model: 'sonnet',
+    roleModel: 'inherit',
+    effort: 'default',
+};
+export const PARALLEL_LIMITS = { min: 1, max: 4 };
+const oneOf = (value, allowed, fallback) => typeof value === 'string' && allowed.includes(value) ? value : fallback;
+/** Keeps every valid field of a stored config and falls back to the default for the rest. */
+export function normalizeConfig(raw) {
+    const data = raw && typeof raw === 'object' ? raw : {};
+    const parallel = data['maxParallelRoles'];
+    return {
+        provider: oneOf(data['provider'], PROVIDER_IDS, DEFAULT_CONFIG.provider),
+        theme: oneOf(data['theme'], ['auto', 'dark', 'light'], DEFAULT_CONFIG.theme),
+        colors: oneOf(data['colors'], COLOR_SCHEME_IDS, DEFAULT_CONFIG.colors),
+        glyphs: oneOf(data['glyphs'], ['auto', 'unicode', 'ascii'], DEFAULT_CONFIG.glyphs),
+        motion: typeof data['motion'] === 'boolean' ? data['motion'] : DEFAULT_CONFIG.motion,
+        // Earlier versions stored on or off.
+        mouse: data['mouse'] === false ? 'off' : oneOf(data['mouse'], MOUSE_IDS, DEFAULT_CONFIG.mouse),
+        maxParallelRoles: typeof parallel === 'number' && Number.isInteger(parallel) && parallel >= PARALLEL_LIMITS.min && parallel <= PARALLEL_LIMITS.max
+            ? parallel
+            : DEFAULT_CONFIG.maxParallelRoles,
+        model: oneOf(data['model'], MODEL_IDS, DEFAULT_CONFIG.model),
+        roleModel: oneOf(data['roleModel'], ROLE_MODEL_IDS, DEFAULT_CONFIG.roleModel),
+        effort: oneOf(data['effort'], EFFORT_IDS, DEFAULT_CONFIG.effort),
+    };
+}
+export function loadConfig(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return { config: { ...DEFAULT_CONFIG } };
+    }
+    try {
+        return { config: normalizeConfig(JSON.parse(text)) };
+    }
+    catch {
+        return { config: { ...DEFAULT_CONFIG }, warning: `Không đọc được ${file}; đang dùng cài đặt mặc định` };
+    }
+}
+/** Writes through a temporary file so an interrupted write never leaves a broken config. */
+export function saveConfig(file, config) {
+    mkdirSync(dirname(file), { recursive: true });
+    const temporary = `${file}.tmp`;
+    writeFileSync(temporary, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    renameSync(temporary, file);
+}

package/dist/core/exec.js

@@ -0,0 +1,32 @@
+import spawn from 'cross-spawn';
+/** Runs a program without a shell. cross-spawn resolves `.cmd` shims on Windows (claude, npm, ...). */
+export const exec = (command, args, options = {}) => new Promise(resolve => {
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let settled = false;
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(result);
+    };
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill();
+    }, options.timeoutMs ?? 30_000);
+    child.stdout?.setEncoding('utf8').on('data', (chunk) => (stdout += chunk));
+    child.stderr?.setEncoding('utf8').on('data', (chunk) => (stderr += chunk));
+    child.on('error', error => finish({ code: null, stdout, stderr, error: error.message }));
+    child.on('close', code => finish({ code: timedOut ? null : code, stdout, stderr, timedOut }));
+    child.stdin?.on('error', () => { });
+    child.stdin?.end(options.input ?? '');
+});
+export const succeeded = (result) => result.code === 0 && !result.error;