{"id":50821527,"url":"https://github.com/xfiveco/chisel-ai-coding-ruleset","last_synced_at":"2026-06-13T14:12:32.781Z","repository":{"id":358666193,"uuid":"1242180953","full_name":"xfiveco/chisel-ai-coding-ruleset","owner":"xfiveco","description":"A ruleset for AI coding agents (Claude Code, Cursor, etc.) working inside a Chisel WordPress theme.","archived":false,"fork":false,"pushed_at":"2026-05-29T07:43:49.000Z","size":137,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-29T09:24:19.139Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xfiveco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-18T07:38:58.000Z","updated_at":"2026-05-29T07:43:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xfiveco/chisel-ai-coding-ruleset","commit_stats":null,"previous_names":["xfiveco/chisel-ai-coding-ruleset"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xfiveco/chisel-ai-coding-ruleset","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xfiveco%2Fchisel-ai-coding-ruleset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xfiveco%2Fchisel-ai-coding-ruleset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xfiveco%2Fchisel-ai-coding-ruleset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xfiveco%2Fchisel-ai-coding-ruleset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xfiveco","download_url":"https://codeload.github.com/xfiveco/chisel-ai-coding-ruleset/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xfiveco%2Fchisel-ai-coding-ruleset/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34287333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-13T14:12:32.042Z","updated_at":"2026-06-13T14:12:32.775Z","avatar_url":"https://github.com/xfiveco.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chisel AI Coding Ruleset\n\nA ruleset for AI coding agents (Claude Code, Cursor, etc.) working inside a Chisel WordPress theme. Ships with every new Chisel project and is read by the agent at the start of every task.\n\nThis README is for **humans maintaining the rules**. The agent itself reads [`CLAUDE.md`](CLAUDE.md) directly — it's the always-loaded entry point that carries the load-bearing rules and routes to the matching reference + skill in [`ai/`](ai/).\n\n## What it covers\n\n- Architecture: core/custom split, where hooks belong, where Twig lives.\n- Design tokens, theme.json, design tool helpers.\n- Block / pattern / ACF block / CPT scaffolding.\n- Gutenberg content insertion via the `xfive-mcp` MCP server.\n- Spacing, base styles, image handling.\n- Three task modes — Figma URL, static asset/mockup, prompt-only.\n\n## How a developer uses it\n\n1. New Chisel project arrives with `CLAUDE.md`, the [`ai/`](ai/) folder, and [`ai-new-session-prompt.md`](ai-new-session-prompt.md) at the theme root.\n2. Launch the agent from inside the theme directory (so the `chisel-*` skills auto-discover), then paste the contents of `ai-new-session-prompt.md` at the start of every new agent session and describe the task.\n3. The agent loads `CLAUDE.md`, then the matching reference + skill for the task, and works in pause-and-review phases. Progress is tracked under an `ai-progress/` folder it creates at the theme root (an `INDEX.md` router → per-effort roadmap → per-phase files); on a new session it reads `ai-progress/INDEX.md` first to resume in-flight work.\n\nThe `xfive-mcp` WordPress plugin must be installed and its MCP server registered in the agent client — content insertion goes through MCP tools, not PHP seeds / WP-CLI / manual paste.\n\n## Structure\n\n```\nCLAUDE.md                          # Entry point — always loaded; carries load-bearing rules + routing index\nai-new-session-prompt.md           # Paste-at-start prompt (phased workflow)\nREADME.md                          # This file\nai-progress/                       # Agent-created at runtime (not shipped): INDEX + per-effort roadmap + per-phase files\nai/\n├── rules/\n│   ├── reference/                 # The \"what\" — descriptive facts\n│   │   ├── file-locations.md\n│   │   ├── design-tokens.md\n│   │   ├── blocks.md\n│   │   ├── section-mapping-decisions.md\n│   │   ├── screen-build-order.md\n│   │   ├── figma-import-template.md\n│   │   ├── progress-template.md\n│   │   ├── mcp-workflow.md\n│   │   ├── coding-conventions.md\n│   │   ├── twig-templating.md\n│   │   ├── assets-and-scripts.md\n│   │   ├── rest-api.md\n│   │   └── woocommerce.md\n│   └── templates/                 # Copy-paste code scaffolds\n│       ├── pattern-markup.md\n│       ├── custom-block-template.md\n│       └── block-mod-template.md\n└── skills/                        # The \"how\" — ordered procedures (auto-discovered slash commands)\n    ├── chisel-figma-to-chisel/    #   Orchestrator for Figma imports\n    ├── chisel-plan/               #   Creates progress files under ai-progress/ (INDEX + per-effort roadmap + per-phase files)\n    ├── chisel-setup-theme-json/\n    ├── chisel-theme-json/\n    ├── chisel-adapt-base-styles/\n    ├── chisel-adapt-header-footer/\n    ├── chisel-create-pattern/\n    ├── chisel-create-block/\n    ├── chisel-create-acf-block/\n    ├── chisel-extend-core-block/\n    ├── chisel-create-component/\n    ├── chisel-create-cpt/\n    └── chisel-create-acf-options/\n```\n\nEach skill lives as `ai/skills/{name}/SKILL.md` — Claude Code auto-discovers them at session start and exposes each as a `/{name}` slash command (e.g. `/chisel-create-pattern`).\n\n**Loading flow:** `CLAUDE.md` (always) → matching `reference/` doc (the \"what\") → matching `skills/` doc (the \"how\") → `templates/` (only when copying code).\n\nReference owns descriptive facts (file structures, decision ladders, token inventory). Skills focus on ordered procedure. Each skill routes back to its reference partner — load the reference first.\n\n## Maintenance principles\n\nWhen adding or editing rules, keep these in mind:\n\n1. **Don't pin specific values.** The rules describe Chisel's **starter** state. Once a project adapts the theme (button padding, border-radius, color hex, spacer slugs), specific values drift. Documented values that go stale make the rules read like factual claims about current state and erode trust. Prefer: \"open the file, compare to the spec, update what diverges\" over \"Chisel defaults are X / Y / Z.\" Only stable invariants belong in rules — protected slug *names* (e.g. `primary`, `tiny`), namespace conventions, file-layout patterns, build-pipeline mechanics.\n\n2. **Reference vs skill.** If you're adding a fact (file list, decision table, token inventory) → reference. If you're adding a procedure (ordered steps to produce something) → skill. Each skill should link to its reference partner, and each reference should route back to the skill(s) that consume it.\n\n3. **Auto-generated files.** Every `_index.scss` barrel in `src/styles/{components,blocks,objects,elements,utilities,generic,vendor,...}` is auto-generated by `chisel-scripts`. Never tell the agent to edit them by hand. `src/design/settings/_index.scss` is the exception — it's hand-edited.\n\n4. **Hooks live in classes, not `functions.php`.** All `add_filter` / `add_action` calls belong in a `custom/app/WP/{Feature}.php` class using the `HooksSingleton` trait. `custom/functions.php` is a bootstrap list of `get_instance()` calls only. Any rule example showing hooks in `functions.php` is wrong.\n\n5. **MCP-only content insertion.** Gutenberg content goes through `xfive-mcp-chisel` MCP tools. Never tell the agent to write PHP seed scripts, WP-CLI commands, or \"ask the user to paste.\"\n\n6. **Verify before asserting.** When adding a fact that names a specific file, class, function, or hook, open the file or grep `core/` to confirm it exists. Rules that name non-existent symbols silently break agents.\n\n7. **Keep examples generic.** Templates and code examples should use `{block-name}` / `{slug}` placeholders, not project-specific names. The rules ship to every Chisel project — examples must be portable.\n\n## Updating across projects\n\nRules are versioned with the Chisel starter theme. When a project runs `npm run update-chisel`, the `core/` folder is overwritten but **the `ai/` folder is part of the project layer** — project-specific edits to `ai/` are preserved. Updates to the canonical ruleset flow out to new projects on theme install (via the Chisel generator) and require manual merge for existing projects.\n\nIf you change a rule that's load-bearing (architecture, hook routing, content-insertion mechanics), bump the rules in `CLAUDE.md` and call it out in the Chisel changelog so existing projects can sync.\n\n## Reporting issues\n\nReal-world validation comes from running tasks against the rules and finding gaps. If an agent stumbles on a task (missing context, contradictory instructions, dead file reference), open an issue with:\n\n- The task you gave the agent (verbatim from `ai-new-session-prompt.md` + task description)\n- What the agent did wrong (or asked about that wasn't in the rules)\n- Which rule doc(s) should cover it\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxfiveco%2Fchisel-ai-coding-ruleset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxfiveco%2Fchisel-ai-coding-ruleset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxfiveco%2Fchisel-ai-coding-ruleset/lists"}