Project State Reader

Project State Reader

Thin wrapper around ${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh. The script parses the project's project_state.md header block and emits structured JSON. This skill exists to give it a Skill-tool-callable name and to document the contract.

Contract

Input: one argument — absolute path to a project folder (the one containing project_state.md).

Output: single JSON object to stdout. Exit code always 0.

Fields:

• project_name — from the H1 line in project_state.md, or folder basename fallback
• codePath — absolute path (string) if declared and resolves, or null if docs-only / unknown
• folder — the absolute path passed in
• playbookSets — (v1.1+) array of dev-guides path slugs the project subscribes to (e.g., ["/best-practices/"]). Falls back to the plugin's defaults.json playbookSets when field absent. Empty array when explicit none.
• playbookSetsSource — (v1.1+) "explicit" (field present with values) \| "explicit-none" (field is literal none) \| "default" (field absent, defaults applied)
• userPlaybook — (v1.1+) absolute path to project-local playbook file, or null when state is unset or docs-only-no-playbook
• userPlaybookState — (v1.1+) "unset" \| "docs-only-no-playbook" \| "set"
• playbookResolutions — (v1.1+) array of {topic, set} entries recording per-topic multi-set contradiction resolutions
• worktreeByDefault — (v1.2+) boolean. When true, /implement always recommends a worktree. Defaults to false when field absent.
• warnings — array of {code, detail} entries

Defensive posture (never throws)

| Input state | Warning code | |---|---| | Project folder does not exist | folder_missing | | Folder exists, project_state.md missing | project_state_md_missing | | project_state.md has no **Code path:** line | code_path_unknown | | **Code path:** /some/dir but that directory doesn't exist | code_path_missing | | Declared (docs-only) sentinel | (none — legitimate docs-only state, codePath is null) |

Code path sentinels in project_state.md

Accepted on the one-line **Code path:** metadata entry:

• **Code path:** /absolute/path — non-null string; path normalized via realpath -m
• **Code path:** (docs-only) — null; explicit docs-only declaration
• (line absent) — null; first-use prompt should fire

Case-insensitive match on the label.

Playbook fields in project_state.md (v1.1+)

**Playbook Sets:** /best-practices/, /best-practices/
**User Playbook:** /home/me/projects/idexx/docs/playbook.md
**User Playbook State:** set

**Playbook Resolutions:**
- font-sizing → /best-practices/
- bem-methodology → /best-practices/

| Line | Semantics | |---|---| | **Playbook Sets:** | Comma-separated set IDs | | **Playbook Sets:** none | Explicit opt-out — empty list, source explicit-none | | (line absent) | Use the plugin's defaults.json playbookSets; source default | | **User Playbook:** | Project-local playbook file | | **User Playbook State:** unset \| docs-only-no-playbook \| set | 3-state field; mirrors Code Path State precedent | | **Playbook Resolutions:** (multi-line list) | Per-topic multi-set choices |

Invocation

"${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh" "/abs/path/to/project/folder"

Parse with jq. Example:

OUTPUT=$("${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh" "$PROJECT_DIR")
CODE_PATH=$(jq -r '.codePath // empty'  0' /dev/null && echo true || echo false)

Consumers (v3.11.0+)

• /ai-dev-assistant:set-code-path — read current value to show in confirm prompt
• /ai-dev-assistant:propose-epics — get codePath before invoking analysis agent
• /ai-dev-assistant:research — pre-analysis hook needs codePath for strong-signal check
• analysis-agent — inputs codePath (resolved by caller; agent doesn't call this skill directly)

Future consumers that need project-level metadata should call this skill rather than parsing project_state.md directly.

Do NOT

• Do not write to project_state.md from this skill. Reading only. Writes go through /set-code-path command or the /new creation flow.
• Do not treat non-empty warnings[] as a blocking error — warnings are observations.
• Do not duplicate the parsing logic elsewhere. Call this skill or the script.

See also

• ${CLAUDE_PLUGIN_ROOT}/scripts/project-state-read.sh — the script
• task-frontmatter-reader skill (v2.0.0) — same design pattern, task-level metadata instead of project-level

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: camoa
• Source: camoa/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.