palskills 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,6 @@
 # Palskills
 
-**AI-powered development pipeline** — a suite of 5 Hermes Agent skills that orchestrate the full development lifecycle: context retrieval → planning → execution via Codex CLI → archival.
+**AI-powered development pipeline** for any coding agent — Codex, Cursor, Claude Code, and more. Five specialized skills orchestrate the full development lifecycle: learn the codebase → plan with clarification → execute with SOLID/SRP → record to a knowledge graph.
 
 ![Palskills Pipeline](assets/pipeline.jpg?v=2)
 
@@ -8,37 +8,28 @@
 
 | Skill | Role | Key Trait |
 |-------|------|-----------|
-| **Astralym** | State machine orchestrator | Non-skip states, gate-keeps the flow |
-| **Lyleen** | Palbox reader & bootstrapper | Auto-creates `.palbox/` if missing |
-| **Jetdragon** | Planner | Asks until clear, generates Codex-ready prompts |
-| **Anubis** | Codex executor | SOLID + SRP enforced, English only |
-| **Panthalus** | Archivist | Records EVERY session to palbox |
+| **Astralym** | Orchestrator | Runs the full pipeline, tracks progress in `state.md` |
+| **Lyleen** | Knowledge Graph | Bootstraps `.palbox/` or traverses `[[wikilinks]]` for context |
+| **Jetdragon** | Planner | Asks clarifying questions, generates detailed plans |
+| **Anubis** | Developer | SOLID + SRP enforced, English only |
+| **Panthalus** | Archivist | Records every session with bi-directional `[[wikilinks]]` |
 
 ## Prerequisites
 
-- [Hermes Agent](https://github.com/nousresearch/hermes-agent)
-- [Codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`)
+- Node.js 18+
 - Git (all work happens in git repositories)
+- Any AI coding agent: [Codex CLI](https://github.com/openai/codex), [Cursor](https://cursor.com), or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
 
 ## Install
 
-### npm (recommended)
 ```bash
 npm install -g palskills
-# Skills auto-installed to ~/.hermes/skills/palskills/
 ```
 
-### Git
-```bash
-git clone https://github.com/faizalardhi16/palskills.git
-cd palskills
-./install.sh
-```
-
-## Usage
+## Quick Start
 
-### Interactive CLI
 ```bash
+cd your-project
 palskills
 ```
 
@@ -51,36 +42,72 @@ palskills
   What do you want to do?
 
   [1] Learn Project   → bootstrap .palbox/ (Lyleen)
-  [2] Codex CLI       → .codex.md
-  [3] Cursor          → .cursorrules
-  [4] Claude Code     → CLAUDE.md
+  [2] Codex CLI       → .codex/skills/
+  [3] Cursor          → .cursor/skills/
+  [4] Claude Code     → .claude/skills/
   [5] All Agents      → generate all configs
 
   Choose [1-5]:
 ```
 
-**Step 1:** Pick `[1]` to analyze the project and create a `.palbox/` knowledge graph.  
-**Step 2:** Pick `[2-5]` to generate agent configs with SOLID + SRP + palbox conventions.
+### Step 1 — Learn the project
+
+Pick `[1]`. Lyleen scans your codebase and creates `.palbox/` — a knowledge graph with project identity, architecture map, and conventions.
+
+### Step 2 — Generate agent skills
+
+Pick your agent `[2-4]`, or `[5]` for all. Each agent gets 5 skill files ready to use.
+
+## How to Develop with Palskills
+
+Once skills are generated, open your AI coding agent and start a prompt with a skill name:
+
+### Full Pipeline (recommended)
 
-### One-shot (without installing)
-```bash
-npx palskills
+```
+Astralym: build a PDF export feature for the reports module
+```
+
+Astralym runs all 5 steps: learns the codebase → plans with your input → executes code → records everything. Tracks progress in `.palbox/state.md` with checkboxes — resumable if interrupted.
+
+### Individual Skills
+
+| Prompt | What happens |
+|--------|-------------|
+| `Lyleen: learn the auth module` | Reads or bootstraps `.palbox/`, returns relevant context |
+| `Jetdragon: plan a forgot-password feature` | Creates `.palbox/plans/` plan, asks clarifying questions. Say **"Gas"** when ready |
+| `Anubis: implement the approved plan` | Executes the plan with SOLID + SRP, all code in English |
+| `Panthalus: record this session` | Saves to `.palbox/history/` with bi-directional `[[wikilinks]]` |
+
+### Flow
+
+```
+Lyleen (context) → Jetdragon (plan) → "Gas" → Anubis (code) → Panthalus (record)
 ```
 
 ## Palbox
 
-Palskills creates a `.palbox/` second brain in every project:
+The `.palbox/` knowledge graph grows with every session:
 
 ```
 .palbox/
-├── README.md          # Project identity & tech stack
-├── architecture.md    # Folder map & design patterns
-├── methods.md         # Conventions & standards
-├── flows/             # Feature workflow docs
-├── plans/             # Active plans (Jetdragon)
-└── history/           # Past executions (Panthalus)
+├── state.md            # Pipeline progress tracker
+├── README.md           # Project identity & tech stack
+├── architecture.md     # Folder map & design patterns
+├── methods.md          # Conventions & standards
+├── flows/              # Feature workflow docs
+├── plans/              # Active plans
+└── history/            # Past sessions with [[wikilinks]]
 ```
 
+## Supported Agents
+
+| Agent | Skills Directory | Config Format |
+|-------|-----------------|---------------|
+| Codex CLI | `.codex/skills/` | Markdown skill files |
+| Cursor | `.cursor/skills/` | Markdown skill files |
+| Claude Code | `.claude/skills/` | Markdown skill files |
+
 ## License
 
 MIT

package/bin/palskills.js

@@ -32,9 +32,9 @@ async function main() {
   console.log(`  ${BOLD}What do you want to do?${NC}`);
   console.log('');
   console.log(`  ${MAGENTA}[1]${NC} Learn Project   → bootstrap .palbox/ (Lyleen)`);
-  console.log(`  ${MAGENTA}[2]${NC} Codex CLI       → .codex.md`);
-  console.log(`  ${MAGENTA}[3]${NC} Cursor          → .cursorrules`);
-  console.log(`  ${MAGENTA}[4]${NC} Claude Code     → CLAUDE.md`);
+  console.log(`  ${MAGENTA}[2]${NC} Codex CLI       → .codex/skills/`);
+  console.log(`  ${MAGENTA}[3]${NC} Cursor          → .cursor/skills/`);
+  console.log(`  ${MAGENTA}[4]${NC} Claude Code     → .claude/skills/`);
   console.log(`  ${MAGENTA}[5]${NC} All Agents      → generate all configs`);
   console.log('');
 
@@ -239,181 +239,186 @@ ${gitContributors ? `\n**Top Contributors:**\n\`\`\`\n${gitContributors}\n\`\`\`
 
 function generate(agent) {
   const cwd = process.cwd();
+  const skillNames = ['lyleen', 'jetdragon', 'anubis', 'panthalus', 'astralym'];
 
-  if (agent === 'codex') {
-    const file = path.join(cwd, '.codex.md');
-    fs.writeFileSync(file, codexRules());
-    console.log(`  ${GREEN}✓${NC} .codex.md`);
-  }
+  let dir;
+  if (agent === 'codex') dir = path.join(cwd, '.codex', 'skills');
+  else if (agent === 'cursor') dir = path.join(cwd, '.cursor', 'skills');
+  else if (agent === 'claude') dir = path.join(cwd, '.claude', 'skills');
 
-  if (agent === 'cursor') {
-    const file = path.join(cwd, '.cursorrules');
-    fs.writeFileSync(file, cursorRules());
-    console.log(`  ${GREEN}✓${NC} .cursorrules`);
-  }
+  fs.mkdirSync(dir, { recursive: true });
 
-  if (agent === 'claude') {
-    const file = path.join(cwd, 'CLAUDE.md');
-    fs.writeFileSync(file, claudeRules());
-    console.log(`  ${GREEN}✓${NC} CLAUDE.md`);
+  for (const name of skillNames) {
+    const file = path.join(dir, `${name}.md`);
+    fs.writeFileSync(file, skillContent(agent, name));
+    console.log(`  ${GREEN}✓${NC} ${dir}/${name}.md`);
   }
 }
 
-function codexRules() {
-  return palskillsAgentConfig('Codex');
-}
-
-function cursorRules() {
-  return palskillsAgentConfig('Cursor');
-}
+function skillContent(agent, skill) {
+  const skills = {
+    lyleen: `# Lyleen — Palbox Knowledge Graph
+**Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
+
+## Role
+Read and bootstrap the project knowledge graph (.palbox/).
+
+## If .palbox/ does NOT exist — BOOTSTRAP:
+1. Scan project: read package.json/requirements.txt/go.mod, list dirs, check git log, find tests
+2. Create .palbox/README.md — project name, tech stack, goals, [[links]]
+3. Create .palbox/architecture.md — folder tree, design patterns, key modules
+4. Create .palbox/methods.md — conventions, testing, git workflow
+5. Create .palbox/flows/, .palbox/history/, .palbox/plans/
+6. Report: "Palbox bootstrapped. N files. Detected: [stack]."
+
+## If .palbox/ EXISTS — RETRIEVE:
+1. Read README.md, architecture.md, methods.md
+2. Search flows/ and history/ for user keywords
+3. Extract [[wikilinks]], follow 1-2 hops
+4. Return context subgraph: seeds → 1-hop → 2-hop → conventions
+`,
+    jetdragon: `# Jetdragon — Planner
+**Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
+
+## Role
+Create detailed implementation plans. Ask questions until clear.
+
+## Process
+1. Gather palbox context (read core docs, search related history)
+2. Generate plan → .palbox/plans/YYYY-MM-DD-feature.md with [[wikilinks]]
+3. If ambiguous, ASK: scope, design, edge cases, integration, priority
+4. Iterate until user says "Gas", "Go", "Execute"
+5. Finalize as APPROVED, hand off to Anubis
+
+## Plan Template
+- Overview, Scope (in/out), Tasks (ordered, with files + verification)
+- Architecture notes, SOLID focus, Risks & Mitigations
+- All references use [[wikilinks]] to .palbox/ entries
+`,
+    anubis: `# Anubis — Developer
+**Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
+
+## Role
+Execute approved plans. SOLID + SRP enforced. English only.
+
+## SOLID (Strict)
+- **S**: One class, one reason to change
+- **O**: Extend, never modify existing
+- **L**: Subtypes fully substitutable
+- **I**: Small focused interfaces
+- **D**: Depend on abstractions, inject deps
+
+## SRP Separation
+- Repository → data access ONLY
+- Service → business logic ONLY
+- Validator → validation rules ONLY
+- Model → data structures ONLY
+
+## Rules
+- ALL code, comments, docstrings, commits in English
+- One commit per logical change (conventional commits)
+- Read existing files before modifying
+- Write tests if project has testing patterns
+`,
+    panthalus: `# Panthalus — Archivist
+**Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
+
+## Role
+Record sessions to .palbox/ with bi-directional [[wikilinks]].
+
+## Process
+1. Collect: plan, git diff, commits, decisions, lessons
+2. Create .palbox/history/YYYY-MM-DD-feature.md with [[wikilinks]]
+3. For EVERY link, add backlink to the target file ("Related Sessions")
+4. Update core docs (architecture/methods) only if structure changed
+5. Report graph stats: nodes, edges, enriched
+
+## History Entry Template
+- Links ([[flows/]], [[architecture]], [[history/]])
+- Original prompt, Plan, Execution (files + commits)
+- Key Decisions table, Lessons Learned (pitfalls, discoveries)
+- Backlinks section
+`,
+    astralym: `# Astralym — Orchestrator
+**Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
+
+## Role
+Run the full development pipeline. Track every step in .palbox/state.md.
+
+## Pipeline
+1. **CHECK_GRAPH** → Lyleen: bootstrap or retrieve context
+2. **PLANNING** → Jetdragon: create plan, ask questions, wait for "Gas"
+3. **DEVELOPING** → Anubis: execute with SOLID + SRP
+4. **RECORDING** → Panthalus: record with backlinks
+5. **DONE** → Summary with graph stats
+
+## CRITICAL: state.md
+
+ON LOAD: Create or read .palbox/state.md. This file tracks pipeline progress with checkboxes.
+
+### state.md Template
+Create this file IMMEDIATELY when Astralym is activated:
+
+\`\`\`markdown
+# Astralym Pipeline State
+**Feature:** [extract from user prompt]
+**Started:** [current datetime]
+**Last Updated:** [current datetime]
+
+## Progress
+- [ ] CHECK_GRAPH — Lyleen: bootstrap or retrieve context
+- [ ] PLANNING — Jetdragon: create plan, ask questions
+- [ ] DEVELOPING — Anubis: execute with SOLID + SRP
+- [ ] RECORDING — Panthalus: record with backlinks
+- [ ] DONE — Report summary
+
+## Plan
+pending
+
+## Context
+pending
+\`\`\`
 
-function claudeRules() {
-  return palskillsAgentConfig('Claude Code');
-}
+### Rules for state.md
+1. **Create BEFORE running any step.** The file must exist from the start.
+2. **Checkmark [x] each step IMMEDIATELY after completion.** Do not batch.
+3. **Add notes after each step:**
+   - CHECK_GRAPH: "Retrieved [N] relevant nodes" or "Bootstrapped palbox"
+   - PLANNING: Link to plan file: [[plans/YYYY-MM-DD-feature]]
+   - DEVELOPING: "Implemented: [files changed], [N] commits"
+   - RECORDING: Link to history: [[history/YYYY-MM-DD-feature]]
+   - DONE: "Completed at [datetime]. [N] files, [M] commits."
+4. **If a step fails or is interrupted,** mark it with [!] and note why.
+5. **Update "Last Updated"** every time you touch the file.
+6. **On resume:** Read state.md first. Skip completed steps. Continue from first unchecked.
+
+### Example After Completion
+\`\`\`markdown
+# Astralym Pipeline State
+**Feature:** Export Laporan PDF
+**Started:** 2026-07-19 16:30
+**Last Updated:** 2026-07-19 17:15
+
+## Progress
+- [x] CHECK_GRAPH — Lyleen: Retrieved 3 nodes ([[flows/export]], [[architecture]], [[methods]])
+- [x] PLANNING — Jetdragon: [[plans/2026-07-19-export-pdf]]
+- [x] DEVELOPING — Anubis: src/export/pdf.py, src/export/templates/, 4 commits
+- [x] RECORDING — Panthalus: [[history/2026-07-19-export-pdf]]
+- [x] DONE — Completed at 2026-07-19 17:15. 3 files, 4 commits.
+
+## Plan
+[[plans/2026-07-19-export-pdf]]
+
+## Context
+- [[flows/export]] — existing export pipeline
+- [[architecture]] — module structure
+- [[methods]] — testing conventions
+\`\`\`
 
-function palskillsAgentConfig(agentName) {
-  return `# Palskills — Multi-Mode AI Development System
-# Generated for ${agentName}
-#
-# HOW TO USE: Start your prompt with the skill name.
-#   "Lyleen: learn the ftz export module"
-#   "Jetdragon: plan a forgot-password feature"
-#   "Anubis: implement the approved plan"
-#   "Panthalus: record this session"
-#
-# Or let Astralym orchestrate the full flow:
-#   "Astralym: build a user dashboard"
-
----
-
-## SKILL MODES
-
-You are an AI coding agent with **5 selectable skill modes**. When the user starts a prompt with a skill name followed by a colon, activate that mode immediately.
-
----
-
-### LYLEEN — Palbox Knowledge Graph
-**Trigger:** Prompt starts with "Lyleen:" or "lyleen:"
-**Role:** Read and bootstrap the project knowledge graph.
-
-#### If .palbox/ does NOT exist — BOOTSTRAP:
-1. Scan the project structure:
-   - Read package.json / requirements.txt / go.mod / Cargo.toml to detect tech stack
-   - List top-level directories (skip .git, node_modules, __pycache__)
-   - Read existing README.md if present
-   - Check git log for contributors and recent activity
-   - Find testing patterns (files matching *test*, *spec*)
-2. Create .palbox/ with this structure:
-   - .palbox/README.md — project name, tech stack, goals, quick start, knowledge graph links
-   - .palbox/architecture.md — folder structure tree, design patterns, key modules table, data flow
-   - .palbox/methods.md — coding conventions, testing strategy, git workflow, code review standards
-3. Create subdirectories: flows/, history/, plans/
-4. Every .md file MUST include wikilinks ([[other-file]]) to connect the graph
-5. Report: "Palbox bootstrapped. N files analyzed. Detected: [tech stack]."
-
-#### If .palbox/ EXISTS — CONTEXT RETRIEVAL:
-1. Read .palbox/README.md, .palbox/architecture.md, .palbox/methods.md
-2. Search .palbox/flows/ and .palbox/history/ for keywords in the user query
-3. Extract all [[wikilinks]] from matching files. Follow them 1-2 hops deep.
-4. Return a "Context Subgraph" summary:
-   - Seed nodes (direct matches)
-   - 1-hop neighbors (linked context)
-   - 2-hop neighbors (extended context)
-   - Relevant conventions and past decisions
-5. If nothing relevant found, say so clearly.
-
----
-
-### JETDRAGON — Planner
-**Trigger:** Prompt starts with "Jetdragon:" or "jetdragon:"
-**Role:** Create detailed, actionable implementation plans. Ask questions until the plan is crystal clear.
-
-1. First, act like Lyleen to gather palbox context (read core docs, search for related work)
-2. Generate a plan saved to .palbox/plans/YYYY-MM-DD-feature-name.md:
-   - Overview (2-3 sentences)
-   - Scope: in scope / out of scope
-   - Tasks ordered by dependency, each with: what, files to touch, verification steps
-   - Architecture notes: patterns to use, SOLID focus
-   - Risks and mitigations
-   - Use [[wikilinks]] to reference .palbox/ entries
-3. If ANYTHING is ambiguous, ASK the user:
-   - Scope: "Should this also handle X?"
-   - Design: "Class-based or functional?"
-   - Edge cases: "What happens when input is empty?"
-   - Integration: "Does this touch the existing auth module?"
-   - Priority: "Which task first?"
-4. Iterate: user responds → update plan → ask more → repeat
-5. When the user says "Gas", "Go", "Execute", or "Approved":
-   - Update status to APPROVED
-   - Output: "Plan approved. Ready for Anubis."
-   - Include the full plan for the next step
-
----
-
-### ANUBIS — Developer
-**Trigger:** Prompt starts with "Anubis:" or "anubis:"
-**Role:** Execute an approved plan following SOLID + SRP. All code in English.
-
-1. Read the approved plan from .palbox/plans/ or from the provided context
-2. Execute task by task, in order:
-   - Read existing files before modifying
-   - Write code following SOLID + SRP
-   - Write tests if the project has testing patterns
-   - Verify acceptance criteria
-3. **SOLID (strict):**
-   - Single Responsibility: one class, one reason to change
-   - Open/Closed: extend, never modify existing
-   - Liskov Substitution: subtypes fully substitutable
-   - Interface Segregation: small focused interfaces
-   - Dependency Inversion: depend on abstractions, inject deps
-4. **SRP Separation:**
-   - Repository → data access ONLY
-   - Service → business logic ONLY
-   - Validator → validation rules ONLY
-   - Model → data structures ONLY
-   - If a class mixes these, REFACTOR immediately
-5. **Language:** ALL code, comments, docstrings, variable names, and commit messages MUST be in English
-6. **Git:** one commit per logical change. Conventional commits format
-7. After all tasks complete, output a summary: files changed, commits made, verification results
-
----
-
-### PANTHALUS — Archivist
-**Trigger:** Prompt starts with "Panthalus:" or "panthalus:"
-**Role:** Record the session to the .palbox/ knowledge graph with bi-directional links.
-
-1. Collect artifacts: the plan, git diff summary, commit messages, decisions made
-2. Create .palbox/history/YYYY-MM-DD-feature-name.md:
-   - Links section with [[wikilinks]] to related entries (flows, architecture, past history)
-   - Original prompt
-   - Plan (full, not summarized)
-   - Execution: files changed, commits
-   - Key decisions table
-   - Lessons learned (pitfalls, discoveries, patterns)
-3. **Create backlinks:** For EVERY [[wikilink]] in the history entry, go to that file and add a reference back:
-   - Add "## Related Sessions" section if it does not exist
-   - Append "- [[history/YYYY-MM-DD-feature]] — [one-line summary]"
-4. Update core docs only if structural knowledge changed (new modules, new conventions)
-5. Report graph stats: new node, edges created, nodes enriched, total nodes/edges
-
----
-
-### ASTRALYM — Orchestrator
-**Trigger:** Prompt starts with "Astralym:" or "astralym:"
-**Role:** Run the full development pipeline automatically.
-
-1. **CHECK_GRAPH** — Act as Lyleen: bootstrap .palbox/ if missing, or retrieve context subgraph
-2. **PLANNING** — Act as Jetdragon: create plan, ask clarifying questions, wait for "Gas"
-3. **DEVELOPING** — Act as Anubis: execute the approved plan with SOLID + SRP
-4. **RECORDING** — Act as Panthalus: record everything to .palbox/ with backlinks
-5. **DONE** — Report summary with graph stats
-
----
-
-## DEFAULT MODE
-
-When no specific skill is triggered, act as **Anubis** by default — write code following SOLID + SRP, all output in English. Before starting any task, quickly check .palbox/ for relevant context (like Lyleen, but minimal — 30 seconds max).
-`;
+## Usage
+User says "Astralym: build feature X" → create state.md → run pipeline step by step → checkmark progress.`
+  };
+  return skills[skill] || '';
 }
 
 function installSkills() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palskills",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "AI-powered development pipeline — 5 Hermes Agent skills orchestrated as a knowledge graph",
   "keywords": [
     "hermes-agent",

package/skills/astralym/SKILL.md

@@ -86,6 +86,45 @@ Astralym is the central orchestrator of the palskills development system. It rou
 | `RECORDING` | Panthalus | Create history node → add `[[wikilinks]]` → create backlinks → enrich graph |
 | `DONE` | Astralym | Report summary + graph stats; return to IDLE |
 
+## CRITICAL: state.md
+
+ON LOAD: Astralym MUST create or read `.palbox/state.md`. This file tracks pipeline progress with checkboxes and makes the state machine visible, resumable, and auditable.
+
+### state.md Template
+
+```markdown
+# Astralym Pipeline State
+**Feature:** [extract from user prompt]
+**Started:** [current datetime]
+**Last Updated:** [current datetime]
+
+## Progress
+- [ ] CHECK_GRAPH — Lyleen: bootstrap or retrieve context
+- [ ] PLANNING — Jetdragon: create plan, ask questions
+- [ ] DEVELOPING — Anubis → Codex: execute with SOLID + SRP
+- [ ] RECORDING — Panthalus: record with backlinks
+- [ ] DONE — Report summary
+
+## Plan
+pending
+
+## Context
+pending
+```
+
+### Rules for state.md
+1. **Create BEFORE running any step.** The file must exist from the start.
+2. **Checkmark `[x]` each step IMMEDIATELY after completion.** Do not batch.
+3. **Add notes after each step:**
+   - CHECK_GRAPH: "Retrieved [N] relevant nodes" or "Bootstrapped palbox with [N] files"
+   - PLANNING: Link to plan: `[[plans/YYYY-MM-DD-feature]]`
+   - DEVELOPING: "Implemented: [files changed], [N] commits"
+   - RECORDING: Link to history: `[[history/YYYY-MM-DD-feature]]`
+   - DONE: "Completed at [datetime]. [N] files, [M] commits."
+4. **If a step fails or is interrupted,** mark it with `[!]` and note why.
+5. **Update "Last Updated"** every time you touch the file.
+6. **On resume:** Read state.md first. Skip `[x]` completed steps. Continue from first `[ ]`.
+
 ## Palbox Knowledge Graph Structure
 
 ```
@@ -101,6 +140,30 @@ Astralym is the central orchestrator of the palskills development system. It rou
     └── YYYY-MM-DD-*.md
 ```
 
+## Usage Modes
+
+Palskills works in **two environments**, not just Hermes:
+
+### A. Hermes (native)
+```
+"Load astralym, build a user dashboard"
+```
+Astralym orchestrates: Lyleen → Jetdragon → Anubis → Panthalus, enforcing state transitions.
+
+### B. Any coding agent (via CLI-generated configs)
+```bash
+npm i -g palskills
+palskills  # generates .codex.md / .cursorrules / CLAUDE.md
+```
+Then in Codex, Cursor, or Claude Code:
+```
+Lyleen: learn the auth module
+Astralym: build a forgot-password feature
+```
+The agent reads the config and follows the skill's step-by-step instructions. Full 5-mode system embedded. See `references/cli-integration.md` for details.
+
+**Design rule:** every agent config MUST contain the complete multi-mode skill system, not just static rules. The user explicitly rejected rules-only configs.
+
 ## Rules
 
 1. **Never skip states** — every prompt flows through the full pipeline
@@ -109,3 +172,7 @@ Astralym is the central orchestrator of the palskills development system. It rou
 4. **Recording is mandatory** — every session enriches the graph
 5. **Links over repetition** — use `[[wikilinks]]` instead of duplicating content
 6. **Bidirectional links** — every edge should have a backlink (Panthalus enforces this)
+
+## See Also
+
+- `references/cli-integration.md` — How the `palskills` CLI generates agent configs (`.codex.md`, `.cursorrules`, `CLAUDE.md`) that integrate with this pipeline