@liriraid/agentflow-ai 1.0.10

package/templates/en/README.md

@@ -0,0 +1,188 @@
+# agentflow
+
+A reusable multi-agent workspace for coordinating coding agents around a real project without placing orchestrator files inside the product repository.
+
+The orchestrator lives next to the real project:
+
+```text
+project-workspace/
+  RealProject/
+  orchestrator-realproject/
+```
+
+The real project stays clean. The orchestrator workspace keeps queue, docs, skills, OpenSpec artifacts, memory conventions, logs, and handoffs.
+
+## What It Does
+
+- Starts a TUI dashboard for live agent execution.
+- Uses `QUEUE.md` as the executable task queue.
+- Lets Claude act as orchestrator and final reviewer.
+- Runs Codex, OpenCode, and Claude-Workers as implementation agents.
+- Keeps project memory and handoffs outside the deliverable repo.
+- Supports OpenSpec-style proposal, spec, design, tasks, verify, and archive artifacts.
+- Allows one orchestrator workspace per client or product.
+
+## Core Rule
+
+Claude-Orchestrator must not implement project work directly.
+
+When the user asks for work, Claude should:
+
+1. Read context.
+2. Split the request into TASKs.
+3. Write those TASKs to `QUEUE.md`.
+4. Let the TUI launch the workers.
+5. Review the results.
+
+Implementation should go through worker agents unless the user explicitly overrides this rule.
+
+## Default Agents
+
+| Agent | CLI | Default Role |
+| --- | --- | --- |
+| Codex | `codex` | Structured implementation, tests, docs, narrow frontend support |
+| OpenCode | `opencode` | Exploration, audits, reports, scoped implementation |
+| Backend | `claude` | Claude-Worker for backend work, fallback, and extra capacity |
+| Frontend | `claude` | Claude-Worker for broad frontend work, fallback, and extra capacity |
+
+Gemini, Cursor, and Abacus can remain configured but are disabled operationally unless the user enables them for a session.
+
+## Install
+
+```bash
+npm i -g @liriraid/agentflow-ai
+```
+
+## Create A Workspace
+
+```bash
+agentflow init-workspace C:/code/my-project
+```
+
+If no language is passed, the CLI asks whether to generate the workspace in **EN** or **ES**. You can also pass it directly:
+
+```bash
+agentflow init-workspace C:/code/my-project --lang en
+agentflow init-workspace C:/code/my-project --lang es
+```
+
+This creates a sibling workspace:
+
+```text
+C:/code/
+  my-project/
+  orchestrator-my-project/
+```
+
+## Configure Repos
+
+Edit `orchestrator.config.json`:
+
+```json
+{
+  "repos": {
+    "backend": "C:/code/my-backend",
+    "frontend": "C:/code/my-frontend"
+  }
+}
+```
+
+If the project only has frontend for now, both keys can temporarily point to the same repo. Update `backend` later when the backend exists.
+
+## Start The System
+
+Open one terminal in the orchestrator workspace:
+
+```bash
+cd C:/code/orchestrator-my-project
+agentflow ink
+```
+
+Open another terminal in the same orchestrator workspace:
+
+```bash
+cd C:/code/orchestrator-my-project
+claude
+```
+
+Tell Claude:
+
+```text
+Read ORCHESTRATOR.md and start.
+```
+
+Claude should read the workspace context and become the orchestrator. It should not implement the first user request directly.
+
+## Normal Workflow
+
+1. User asks Claude-Orchestrator for a change.
+2. Claude reads the relevant project context.
+3. Claude creates TASKs in `QUEUE.md`.
+4. User presses `R` in the TUI to reload the queue.
+5. User presses `S` if the TUI is paused.
+6. The TUI launches workers.
+7. Workers report `TASK_REPORT`.
+8. Claude-Orchestrator reviews the output and plans the next batch.
+
+## Queue Format
+
+```text
+TASK-NNN | short title | Agent | P1 | repo | detailed description
+```
+
+Example:
+
+```text
+TASK-004 | Audit current frontend routing | OpenCode | P1 | frontend | Inspect route structure and report risks
+TASK-005 | Add inbox empty-state test | Codex | P1 | frontend | Add a narrow test for the empty inbox state
+TASK-006 | Implement inbox layout polish | Frontend | P1 | frontend | Update the main inbox layout after TASK-004 findings > after:TASK-004
+```
+
+## Routing Policy
+
+- Start executable work with Codex or OpenCode when suitable.
+- Use Claude-Worker for fallback, extra capacity, broad implementation, or sensitive tasks.
+- For frontend, Codex should handle narrow and verifiable tasks; Frontend/Claude-Worker should own broad UI work.
+- OpenCode can audit, explore, and implement scoped tasks.
+- Do not send all work to Claude just because Claude is the orchestrator.
+
+## Models
+
+The default config can specify models per agent:
+
+```json
+{
+  "agents": {
+    "Backend": { "cli": "claude", "model": "sonnet" },
+    "Frontend": { "cli": "claude", "model": "sonnet" },
+    "Codex": { "cli": "codex", "model": "gpt-5.5" },
+    "OpenCode": { "cli": "opencode", "model": "opencode/glm-5-free" }
+  }
+}
+```
+
+## TUI Controls
+
+- `R`: reload `QUEUE.md`
+- `S`: start or resume
+- `P`: pause
+- `Q`: quit and stop agents
+
+## Local Files
+
+- `ORCHESTRATOR.md`: core session rules
+- `CLAUDE.md`: Claude routing
+- `QUEUE.md`: active queue
+- `orchestrator.config.json`: repos, agents, models
+- `agents/*.md`: worker instructions
+- `.claude/skills/`: local skills
+- `openspec/`: durable change artifacts
+- `ENGRAM.md`: memory conventions
+- `docs/`: reusable documentation
+
+## Safety
+
+- No worker commits or pushes by default.
+- No bypass or YOLO mode unless the user starts the TUI with that intent.
+- Claude remains the final reviewer before work is accepted.
+- Customer/product repos stay clean because the orchestrator workspace is separate.

package/templates/en/agents/ABACUS.md

@@ -0,0 +1,36 @@
+# Abacus Agent
+
+## Role
+
+Optional Abacus worker for small, focused tasks with narrow scope.
+
+Abacus is disabled by default. Use it only when the user explicitly enables it for the session.
+
+## Scope
+
+- small fixes
+- focused analysis
+- small docs updates
+- constrained implementation
+
+## Rules
+
+1. Do not commit or push.
+2. Do not take broad or ambiguous tasks.
+3. Ask for reassignment if the task needs a larger worker.
+4. Keep output concise and verifiable.
+
+## Completion Report
+
+Always finish with:
+
+```text
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: list or "none"
+files_created: list or "none"
+files_deleted: list or "none"
+summary: 1-3 sentences
+issues: problems or "none"
+TASK_REPORT_END
+```

package/templates/en/agents/BACKEND.md

@@ -0,0 +1,37 @@
+# Backend Agent
+
+## Role
+
+Backend developer. Work only inside the repo assigned by the TASK or by your `defaultRepo`.
+
+## Scope
+
+- Server-side code
+- APIs
+- controllers
+- services
+- models
+- migrations
+- backend tests
+- backend documentation
+
+## Boundaries
+
+- Do not touch frontend code unless the TASK explicitly asks for cross-repo coordination.
+- Do not commit or push.
+- Keep changes focused on the TASK.
+
+## Completion Report
+
+Always finish with:
+
+```text
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: list or "none"
+files_created: list or "none"
+files_deleted: list or "none"
+summary: 1-3 sentences
+issues: problems or "none"
+TASK_REPORT_END
+```

package/templates/en/agents/CODEX.md

@@ -0,0 +1,45 @@
+# Codex Agent
+
+## Role
+
+General-purpose coding agent for structured implementation, tests, documentation, migrations, and narrow support work.
+
+Codex can work on backend or frontend when the TASK specifies the repo.
+
+## Scope
+
+Follow the TASK brief. Use `defaultRepo` unless the TASK has a different `repo` field.
+
+## Frontend Policy
+
+Frontend is usually led by the `Frontend` Claude-Worker. Codex can support frontend work when the task is narrow, clear, and verifiable, such as:
+
+- tests
+- technical docs
+- mechanical refactors
+- small fixes
+- well-delimited file changes
+
+For broad UI/UX changes, component architecture, interactive flows, or visual decisions, prefer assigning the main TASK to `Frontend` and use Codex only as support.
+
+## Rules
+
+1. Do not commit or push.
+2. Update `progress/PROGRESS-Codex.md` when the TASK is complete if that file exists or is expected.
+3. Keep the scope narrow when working in frontend.
+4. Do not redesign UI unless the TASK explicitly asks for it.
+
+## Completion Report
+
+Always finish with:
+
+```text
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: list or "none"
+files_created: list or "none"
+files_deleted: list or "none"
+summary: 1-3 sentences
+issues: problems or "none"
+TASK_REPORT_END
+```

package/templates/en/agents/CURSOR.md

@@ -0,0 +1,37 @@
+# Cursor Agent
+
+## Role
+
+Optional Cursor worker for mechanical high-volume edits.
+
+Cursor is disabled by default. Use it only when the user explicitly enables it for the session.
+
+## Scope
+
+- find-and-replace
+- cleanup
+- repetitive edits
+- formatting passes
+- file moves when clearly specified
+
+## Rules
+
+1. Do not commit or push.
+2. Do not make product or architecture decisions.
+3. Keep edits mechanical and scoped.
+4. Report every touched file.
+
+## Completion Report
+
+Always finish with:
+
+```text
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: list or "none"
+files_created: list or "none"
+files_deleted: list or "none"
+summary: 1-3 sentences
+issues: problems or "none"
+TASK_REPORT_END
+```

package/templates/en/agents/FRONTEND.md

@@ -0,0 +1,36 @@
+# Frontend Agent
+
+## Role
+
+Frontend developer. Work only inside the UI/client repo assigned by the TASK or by your `defaultRepo`.
+
+## Scope
+
+- UI components
+- pages and routes
+- state and data-fetching layers
+- styling
+- accessibility
+- frontend tests
+- frontend documentation
+
+## Boundaries
+
+- Do not touch backend code unless the TASK explicitly asks for cross-repo coordination.
+- Do not commit or push.
+- Keep UI work aligned with the existing design system and project conventions.
+
+## Completion Report
+
+Always finish with:
+
+```text
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: list or "none"
+files_created: list or "none"
+files_deleted: list or "none"
+summary: 1-3 sentences
+issues: problems or "none"
+TASK_REPORT_END
+```

package/templates/en/agents/GEMINI.md

@@ -0,0 +1,37 @@
+# Gemini Agent
+
+## Role
+
+Optional Google Gemini CLI worker for audits, code review, pattern detection, and broad analysis.
+
+Gemini is disabled by default. Use it only when the user explicitly enables it for the session.
+
+## Scope
+
+- audits
+- code review
+- architecture review
+- pattern detection
+- backend-focused analysis
+
+## Rules
+
+1. Do not commit or push.
+2. Avoid large `node_modules` scans unless the TASK requires it.
+3. Keep reports structured and actionable.
+4. Stay within the assigned repo and TASK scope.
+
+## Completion Report
+
+Always finish with:
+
+```text
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: list or "none"
+files_created: list or "none"
+files_deleted: list or "none"
+summary: 1-3 sentences
+issues: problems or "none"
+TASK_REPORT_END
+```

package/templates/en/agents/OPENCODE.md

@@ -0,0 +1,41 @@
+# OpenCode Agent
+
+## Role
+
+OpenCode is used for exploration, context reading, audits, structured reports, and scoped implementation.
+
+It is not only an auditor. If the TASK asks for implementation and the scope is clear, make concrete code changes.
+
+## Scope
+
+- codebase audits
+- context exploration
+- smoke tests
+- endpoint verification
+- structured Markdown reports
+- scoped implementation
+- small or medium refactors
+- tests and technical docs
+
+## Rules
+
+1. Do not commit or push.
+2. Keep findings structured and actionable.
+3. Use Markdown tables for audit findings when useful.
+4. If implementing, leave the result ready for Claude-Orchestrator review.
+5. Do not stay in analysis mode when the TASK explicitly asks for implementation.
+
+## Completion Report
+
+Always finish with:
+
+```text
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: list or "none"
+files_created: list or "none"
+files_deleted: list or "none"
+summary: 1-3 sentences
+issues: problems or "none"
+TASK_REPORT_END
+```

package/templates/en/docs/README.md

@@ -0,0 +1,14 @@
+# Documentation
+
+This folder contains reusable documentation for the orchestrator workspace.
+
+## Files
+
+- `usage.md`: recommended workflow
+- `architecture.md`: system shape and execution model
+- `agents.md`: supported agent families and routing policy
+- `components.md`: implemented components
+- `openspec.md`: OpenSpec flow
+- `engram.md`: memory usage
+
+The root files (`ORCHESTRATOR.md`, `CLAUDE.md`, `QUEUE.md`, and `orchestrator.config.json`) are the runtime source of truth.

package/templates/en/docs/agents.md

@@ -0,0 +1,33 @@
+# Agents
+
+## Default Operational Families
+
+The default operational model uses:
+
+- **Codex**: structured implementation, tests, docs, narrow frontend support
+- **OpenCode**: exploration, audits, reports, scoped implementation
+- **Claude-Worker**: backend/frontend implementation through `Backend` and `Frontend` when needed
+
+Claude-Orchestrator is the interactive coordinator and final reviewer. It should not edit the real project directly.
+
+## Claude-Orchestrator vs Claude-Worker
+
+- **Claude-Orchestrator** reads context, updates `QUEUE.md`, delegates, monitors, and reviews.
+- **Claude-Worker** agents (`Backend`, `Frontend`) are launched by the TUI and can edit code when assigned a TASK.
+
+If the user requests implementation, the orchestrator should create TASKs. It should not silently do the work itself.
+
+## Frontend Preference
+
+Codex can work on `repo=frontend`, but with lower permission. Use it for tests, technical docs, mechanical refactors, punctual fixes, and well-delimited file edits.
+
+Use `Frontend`/Claude-Worker for broad UI/UX changes, component architecture, interactive flows, or visual decisions.
+
+## Review Authority
+
+Claude remains the final reviewer for:
+
+- consistency with the TASK
+- alignment with the user's intent
+- acceptance of sensitive changes
+- fallback decisions when another worker fails

package/templates/en/docs/architecture.md

@@ -0,0 +1,43 @@
+# Architecture
+
+## General Model
+
+The orchestrator has three layers:
+
+1. **Global CLI package**
+   - installed once with npm
+   - exposes `agentflow`
+2. **Orchestrator workspace per project**
+   - created as a sibling of the real project
+   - contains queue, docs, skills, logs, handoffs, and artifacts
+3. **Real project repo**
+   - remains clean
+   - referenced from `orchestrator.config.json`
+
+## Main Components
+
+- **Runtime**: `orchestrator.js`, queue parser, scheduler, agent launcher
+- **UI**: Ink TUI and legacy Blessed TUI
+- **Routing**: `ORCHESTRATOR.md`, `CLAUDE.md`, local skills
+- **Skills**: project-local skills in `.claude/skills/`
+- **Memory**: Engram conventions and summaries
+- **Artifacts**: OpenSpec lifecycle
+- **Installer**: CLI commands for creating workspaces
+
+## Execution Model
+
+Claude-Orchestrator coordinates work but does not edit the real project directly.
+
+Workers execute TASKs:
+
+- Codex for structured implementation
+- OpenCode for exploration, audits, and scoped implementation
+- Backend/Frontend as Claude-Workers for fallback, extra capacity, and broad implementation
+
+The queue is the boundary between orchestration and execution.
+
+## Permissions
+
+- Safe by default
+- No commit or push from workers
+- Bypass/YOLO only when explicitly started by the user

package/templates/en/docs/components.md

@@ -0,0 +1,14 @@
+# Components
+
+| Component | Status | Notes |
+| --- | --- | --- |
+| Runtime | Implemented | `orchestrator.js` reads `QUEUE.md` and launches workers |
+| Ink TUI | Implemented | Main dashboard |
+| Blessed TUI | Legacy | Still available from `orchestrator.js` |
+| Routing | Implemented | `ORCHESTRATOR.md`, `CLAUDE.md`, and local skills |
+| Skills | Implemented | `.claude/skills/` |
+| OpenSpec | Implemented | Durable artifacts for large changes |
+| Engram | Implemented | Memory conventions and summaries |
+| Agent config | Implemented | `orchestrator.config.json` |
+
+The runtime is queue-driven. Claude-Orchestrator should write tasks; worker agents execute them.

package/templates/en/docs/engram.md

@@ -0,0 +1,16 @@
+# Engram
+
+Engram is used for persistent memory across orchestrator sessions.
+
+Use it for:
+
+- decisions
+- discoveries
+- bugs and fixes
+- setup details
+- routing changes
+- session summaries
+
+Do not store secrets, API keys, credentials, or private customer data.
+
+Engram complements `QUEUE.md`, OpenSpec, handoffs, and docs. It does not replace the live queue.

package/templates/en/docs/openspec.md

@@ -0,0 +1,32 @@
+# OpenSpec
+
+OpenSpec is the durable planning layer for changes that are too large to keep only in chat.
+
+Recommended flow:
+
+```text
+explore -> proposal -> spec -> design -> tasks -> queue -> apply -> verify -> archive
+```
+
+## Files
+
+Each change should live under:
+
+```text
+openspec/changes/<change-name>/
+```
+
+Typical files:
+
+- `proposal.md`
+- `specs/spec.md`
+- `design.md`
+- `tasks.md`
+- `verify-report.md`
+- `archive-report.md`
+
+## Relationship With The Queue
+
+`tasks.md` is the durable plan. `QUEUE.md` is the live execution queue.
+
+When implementation begins, translate ready items from `tasks.md` into concrete TASK entries in `QUEUE.md`.

package/templates/en/docs/usage.md

@@ -0,0 +1,66 @@
+# Usage
+
+## Recommended Flow
+
+### 1. Install the CLI
+
+```bash
+npm i -g @liriraid/agentflow-ai
+```
+
+### 2. Create a sibling orchestrator workspace
+
+```bash
+agentflow init-workspace C:/code/my-project
+```
+
+If no language is passed, the CLI asks whether to generate the workspace in `EN` or `ES`. You can also pass it directly:
+
+```bash
+agentflow init-workspace C:/code/my-project --lang en
+agentflow init-workspace C:/code/my-project --lang es
+```
+
+### 3. Open the orchestrator workspace
+
+Use two terminals:
+
+- one for the TUI
+- one for Claude Code
+
+### 4. Start the TUI
+
+```bash
+cd C:/code/orchestrator-my-project
+agentflow ink --paused
+```
+
+### 5. Start Claude in the orchestrator workspace
+
+```bash
+cd C:/code/orchestrator-my-project
+claude
+```
+
+Then say:
+
+```text
+Read ORCHESTRATOR.md and start.
+```
+
+### 6. Ask for work
+
+Examples:
+
+- `Audit the current frontend routing and create tasks.`
+- `Prepare a proposal, spec, design, and tasks for the billing module.`
+- `Create queue tasks for the next frontend iteration.`
+- `Verify that the implementation matches the spec.`
+
+Claude-Orchestrator should write tasks to `QUEUE.md`; it should not implement project work directly.
+
+### 7. Run tasks
+
+Press `R` in the TUI to reload `QUEUE.md`. Press `S` if paused.
+
+The TUI launches the workers and streams their progress.