| name | project-context |
| description | Shared context-resolution pattern for workflow commands. Encodes the canonical
3-step protocol (read config, auto-detect, validate) with extension points
for command-specific behavior. Use when: resolving project context, reading
workflow config, or auto-detecting project settings.
|
| domains | ["project","context","configuration","workflow"] |
| user-invocable | false |
Project Context Resolution Protocol
Canonical 3-step protocol for resolving project context in workflow commands. Commands reference this skill instead of duplicating the pattern inline.
Core Protocol
Step 1: Read Config
Use the Read tool to read .claude/workflow.yaml.
- If file exists: extract all fields. Read
project.remote (default: origin if field is absent or empty). Use this as the identity remote name for any git remote get-url or gh --repo resolution. Proceed to Step 3 (Validate).
- If file does not exist: proceed to Step 2 (Auto-Detect).
Step 2: Auto-Detect (Zero-Config Fallback)
Behavior varies by mode. Commands specify which mode to use; Full is the default.
| Mode | Project File Scan | Test/Lint Inference | Ecosystem Detection | Confirmation Prompt |
|---|
| Full (default) | Yes | Yes | No | "I detected [language] project [org/repo] with test command [inferred]. Is this correct?" |
| Lightweight | Yes | No | No | "I detected [language] project [org/repo]. Is this correct?" |
| Minimal | No | No | No | "I detected [org/repo]. Is this correct?" |
| Ecosystem | Yes | No | Yes (read coding-workflows:stack-detection skill) | "I detected [language] project [org/repo] with ecosystem [detected]. Is this correct?" |
Common across all modes:
- Run
git remote get-url origin to extract org and repo name
- CONFIRM with user using the mode-specific prompt. DO NOT proceed without confirmation.
When project file scan is enabled, scan for: pyproject.toml, package.json, Cargo.toml, go.mod, Gemfile.
When ecosystem detection is enabled, read the coding-workflows:stack-detection skill and use its tables for language + framework detection. Store the resolved ecosystem identifier for use in later steps (the consuming command specifies where).
Step 3: Validate
project.org and project.name must be non-empty (stop if missing)git_provider must be github (stop with message if not) -- unless the command specifies a conditional override- If
project.remote is set to a non-empty value but git remote get-url {remote} fails: stop with error: "Configured remote '{remote}' not found. Run git remote -v to see available remotes, or update project.remote in .claude/workflow.yaml." Do NOT silently fall back to origin.
DO NOT GUESS configuration values. If a value cannot be read from workflow.yaml or confirmed via auto-detection, ask the user.
Validation Extensions
Commands may add validation checks beyond the core protocol.
| Extension | Behavior | Override Pattern |
|---|
| Test Command Check | Additionally validate commands.test.full exists (warn if missing, skip test steps) | Command adds to override block |
| Conditional git_provider | Replace default git_provider validation with command-specific conditional logic | Command replaces validation inline |
Target Safety
Once a target is resolved in Step 0 (whether from config or auto-detect), it is locked:
- Never re-resolve after a CLI failure
- Never silently substitute with a different remote or target
- Present diagnostic information on failure, then STOP
Cross-reference: coding-workflows:issue-workflow Target Safety (lines 42-50) for the full principle and rationale (#224).
Anti-Patterns
- Silent remote fallback after failure (#224) -- never substitute a different remote or target after a CLI command fails
- Guessing configuration values -- if a value cannot be read or confirmed, ask the user
- Skipping user confirmation in auto-detect path -- always confirm, regardless of mode
- Re-resolving target after CLI command failure -- the resolved target is locked for the session
- Adding ecosystem/test detection to Minimal-mode commands -- defeats the purpose of reduced scope
Cross-References
coding-workflows:stack-detection -- used by Ecosystem auto-detect modecoding-workflows:issue-workflow -- Target Safety principle, execution-phase Step 0
Consuming commands:
plan-issue (Full, no overrides)execute-issue (Full + Test Command Check)execute-issue-worktree (Full + Test Command Check)design-session (Lightweight)prepare-issue (Lightweight)review-plan (Lightweight)merge-issue (Minimal)cleanup-worktree (Minimal)create-issue (Full + Conditional git_provider)review-pr (Ecosystem)
