palskills 1.0.6 → 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

@@ -343,7 +343,7 @@ Record sessions to .palbox/ with bi-directional [[wikilinks]].
 **Agent:** ${agent === 'codex' ? 'Codex' : agent === 'cursor' ? 'Cursor' : 'Claude Code'}
 
 ## Role
-Run the full development pipeline automatically.
+Run the full development pipeline. Track every step in .palbox/state.md.
 
 ## Pipeline
 1. **CHECK_GRAPH** → Lyleen: bootstrap or retrieve context
@@ -352,9 +352,71 @@ Run the full development pipeline automatically.
 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
+\`\`\`
+
+### 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
+\`\`\`
+
 ## Usage
-User says "Astralym: build feature X" → full pipeline runs.
-`
+User says "Astralym: build feature X" → create state.md → run pipeline step by step → checkmark progress.`
   };
   return skills[skill] || '';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palskills",
-  "version": "1.0.6",
+  "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