Fairy Tale

fairy_tale

日本語版 README

Research workspace for turning public Fable/Mythos-class agent reports into reproducible workflow-augmentation skills and plugin packages.

Think of this project as the nightingale's scorebook.

In Andersen's tale, the court becomes enchanted by a jeweled mechanical bird, only to learn that the living song matters more than the glittering machine. Fairy Tale does not try to steal the bird, open the cage, or pretend to be the emperor's locksmith. It studies public descriptions and field reports of unusually good agent work, separates melody from myth, and writes down the repeatable patterns as skills, checks, adapters, and sample results.

This repository does not attempt to bypass access controls, export controls, or model safeguards. It studies public official information and public user reports to define reusable workflow enhancements that can be run with Codex, Claude Code, or other agent-skill-compatible coding assistants.

Quick Start

Install the Claude Code plugin directly from GitHub:

/plugin marketplace add bonginkan/fairy_tale
/plugin install fairy-tale@fairy-tale-marketplace

Codex's current plugin CLI supports GitHub shorthand marketplaces such as owner/repo. Add the repository as a marketplace, then install fairy-tale:

codex plugin marketplace add bonginkan/fairy_tale
codex plugin add fairy-tale@fairy-tale-marketplace

If your Codex build does not expose the plugin CLI yet, use the plugin directory UI and add bonginkan/fairy_tale as a marketplace source.

For skill-only use without a plugin, install just the canonical skills:

mkdir -p "$HOME/.codex/skills"
curl -fsSL https://raw.githubusercontent.com/bonginkan/fairy_tale/main/install.sh | sh -s -- --agent codex

Use --agent claude for ~/.claude/skills, --agent agents for ~/.agents/skills, or --target /absolute/skills/dir for an explicit target. The installer fails closed if the target directory is missing unless --create is supplied.

From a source checkout, use the unified repository CLI to discover and run the same workflow checks without memorizing individual script paths:

./fairy --help
./fairy doctor
./fairy validate
./fairy task-card --help
./fairy ledger --help
./fairy fusion --help
./fairy e3 --help

doctor validates an optional caller-repository .fairy/profile.json, then runs residency and adapter health checks. validate runs the deterministic CI suite, while Task Card and Validation Ledger operations remain thin delegates to scripts/task_artifacts.py. Fairy Fusion execution and its bounded, decision-only automatic trigger check delegate to the existing fusion runner. E3 provides a machine-validated Estimate, Execute, and bounded Expand state machine for checkable tasks with multiple plausible scope levels. See Fairy CLI, E3 Minimum-Sufficient Execution, and automatic trigger decisions. The skill-only installer intentionally does not install a host executable or modify PATH; use the CLI from a source checkout.

Repository-local workflow rules use the closed, declarative Fairy profile. Task Cards capture the profile and Ledgers preserve the same snapshot; profile commands are never executed as hooks.

Before publishing benchmark claims or making the repository public, read SECURITY.md, CONTRIBUTING.md, and Feedback governance.

Before a long benchmark, multi-agent run, or context-heavy coding task, verify that Fairy Tale is still resident in the repo skills and plugin package:

python3 scripts/fairy_tale_residency_check.py

Validate adapter manifests with the same command used by the CI adapter job:

cargo run --manifest-path crates/fairy-adapter-runner/Cargo.toml -- validate

Use --check-installed --strict-installed when you also want to require machine-level Codex, Claude Code, and AGENTS skill installs.

For tasks where visible context may be incomplete, use the domain-neutral Latent Structure Harness to record observations, negative evidence, hypotheses, inferred invariants, probes, and validators before promoting a local pattern into a general rule.

For long or tightly scoped work, create a machine-valid Task Card and Validation Ledger. The linked JSON artifacts preserve the objective, allowed targets, explicit budget, stop conditions, planned checks, results, blockers, evidence paths, and remaining risk across handoffs and context resumes.