Shen-Hua

Shen-Hua is a Codex skill pack for long-running project work. It turns a broad goal into a disciplined agent workflow with planning, local task queueing, runtime memory, verification, self-review, and handoff.

It is not a model clone, not an autonomy bypass, and not a way to remove Codex runtime limits. It is a practical workflow layer that makes long tasks easier to resume, audit, and verify.

What It Adds

• $shen-hua as one top-level entrypoint.
• Planning before risky multi-file changes.
• Local task queue and event log under .agent/state/.
• Searchable project memory index.
• Resume and automation prompts for future Codex sessions.
• Verification gate for skill validity and runtime state.
• Self-review and handoff discipline before finishing work.
• Optional external-sync outbox for GitHub, Linear, or another task system.

Skills Included

Skill	Purpose
shen-hua	Top-level entrypoint for the full workflow.
project-commander	Main controller for goals, plans, tasks, and progress.
deep-planner	Investigation and phase planning before complex changes.
subagent-orchestrator	Splits work into bounded subagent or local specialist roles.
persistent-memory	Maintains .agent/ project memory.
runtime-operator	Operates task queue, event log, memory index, resume prompt, gate, and sync export.
verification-loop	Runs checks, fixes failures, and repeats verification.
self-reviewer	Reviews requirements, diff risk, tests, and residual issues.
handoff-writer	Writes resume-ready handoff notes.

Install

Repository-scoped install

Copy the skill folders into the project where you want Codex to use them:

New-Item -ItemType Directory -Force .\.agents\skills
Copy-Item -Recurse .\skills\* .\.agents\skills\

Optional project rules:

Copy-Item .\templates\AGENTS.md .\AGENTS.md

User-scoped install

Windows:

.\install.ps1

macOS/Linux:

./install.sh

By default these copy skills to your user skill folder. You can also pass a destination:

.\install.ps1 -Destination "C:\path\to\project\.agents\skills"

./install.sh /path/to/project/.agents/skills

Use

Invoke the full workflow:

$shen-hua Build this feature end to end: ...
$shen-hua Continue the current project from the last handoff.
$shen-hua Read the queue, pick the next safe task, verify it, and write a handoff.

Invoke narrower skills when needed:

$deep-planner Plan this refactor before editing.
$runtime-operator Rebuild the memory index and show the queue.
$verification-loop Check and fix the current failing tests.
$handoff-writer Write a clean handoff for the next session.

Runtime Commands

After installing into a project, Shen-Hua can create local runtime state:

py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py init
py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py task list
py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py search "next action"
py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py resume
py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py sync-export
py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py gate

The runtime creates project-local files under .agent/. These are intentionally not included in this repository because they are per-project working state.

Verification

Validate the pack before publishing or after edits:

python scripts/validate.py

The validator checks skill frontmatter, required files, and Python syntax for bundled scripts.

What This Does Not Do

• It does not run forever by itself. Use Codex automation/heartbeat if you want scheduled continuation.
• It does not force remote tools to exist. External sync needs your chosen service and credentials.
• It does not add hidden model memory or a larger context window.
• It does not replace tests, CI, code review, or human judgment.

License

MIT