corgispec-gh-propose - SKILL.md Agent Skill

name: corgispec-gh-propose description: Propose a new change with all artifacts generated in one step and tracked via GitHub issues. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. license: MIT compatibility: Requires corgispec CLI. metadata: author: corgispec version: "1.0" generatedBy: "1.3.0"

Propose a new change - create the change and generate all artifacts in one step.

I'll create a change with artifacts:

proposal.md (what & why)
design.md (how)
tasks.md (implementation steps)

After explicit review of the proposal/spec/design/tasks package, continue with /corgi-apply.

Input: The user's request should include a change name (kebab-case) OR a description of what they want to build.

Steps

If no clear input provided, ask what they want to build

Use the AskUserQuestion tool (open-ended, no preset options) to ask:

"What change do you want to work on? Describe what you want to build or fix."

From their description, derive a kebab-case name (e.g., "add user authentication" → add-user-auth).

IMPORTANT: Do NOT proceed without understanding what the user wants to build.
Check isolation mode and set up worktree (if configured)

Context Gate: If your session context already contains:
- isolation.mode value
- Current branch → Gate passed: Use these values. Proceed to worktree creation step.
If NOT available, read openspec/config.yaml and check for isolation settings:
```
# Worktree isolation config (optional)
isolation:
  mode: worktree    # worktree | none (default: none)
  root: .worktrees  # worktree root directory (default: .worktrees)
  branch_prefix: feat/  # feature branch prefix (default: feat/)
```
If isolation.mode is worktree:
- Derive worktree path: <root>/<name> (e.g., .worktrees/add-fart-tracking)
- Derive branch name: <branch_prefix><name> (e.g., feat/add-fart-tracking)
- Check if the worktree already exists:
```
git worktree list --porcelain 2>/dev/null | grep "worktree.*/<name>$"
```
- If worktree exists → reuse it (announce: Reusing existing worktree at <path>)
- If worktree does not exist → create it:
```
git worktree add <root>/<name> -b <branch_prefix><name>
```
- From this point on, ALL subsequent steps run inside the worktree. Use the Bash tool's workdir parameter set to the absolute worktree path for every command. File reads and writes also use absolute paths within the worktree.
- Announce: Worktree created at <path> (branch: <branch_name>)
If isolation.mode is none or isolation section is missing:
- Continue as today — work in the current directory
- Skip the worktree-only closeout step below (Step 9)
Check for an existing change directory and issue tracking

Before running corgispec propose, check whether openspec/changes/<name>/ already exists.
- If the change exists and has .github.yaml, announce that GitHub tracking is already configured and skip GitHub issue creation later.
- If the change exists without .github.yaml, reuse the change directory and allow Step 6 to create issues later.
- If the change does not exist, continue to Step 4.
Create or reuse the change directory
```
corgispec propose "<name>"
```
If the change does not already exist, this creates a scaffolded change at openspec/changes/<name>/ with .openspec.yaml. If it already exists, reuse the existing change directory instead of creating a new one.
Develop: Get the artifact build order and build the artifact package
```
corgispec status "<name>" --json
```
Parse the JSON to get:
- applyRequires: array of artifact IDs needed before implementation (e.g., ["tasks"])
- artifacts: list of all artifacts with their status and dependencies
Create artifacts in sequence until all implementation-required artifacts are complete

Use the TodoWrite tool to track progress through the artifacts.

Loop through artifacts in dependency order (artifacts with no pending dependencies first):

a. For each artifact that is ready (dependencies satisfied):
- Get instructions:
```
corgispec instructions <artifact-id> --change <name> --json
```
- The instructions JSON includes:
  - context: Project background (constraints for you - do NOT include in output)
  - rules: Artifact-specific rules (constraints for you - do NOT include in output)
  - template: The structure to use for your output file
  - instruction: Schema-specific guidance for this artifact type
  - outputPath: Where to write the artifact
  - dependencies: Completed artifacts to read for context
- Read any completed dependency files for context
- Create the artifact file using template as the structure
- Apply context and rules as constraints - but do NOT copy them into the file
- Show brief progress: "Created "
b. Continue until all applyRequires artifacts are complete - After creating each artifact, re-run corgispec status "<name>" --json - Check if every artifact ID in applyRequires has status: "done" in the artifacts array - Stop when all applyRequires artifacts are done

c. If an artifact requires user input (unclear context):
- Use AskUserQuestion tool to clarify
- Then continue with creation
The primary output of propose is the completed planning artifact package: proposal -> {spec, design} -> tasks.
Closeout: Show final status and prepare handoff state
```
corgispec status "<name>"
```
After the artifacts are complete, prepare the local handoff state that later phases consume. The planning artifact package remains the primary output; tracker setup and worktree metadata are closeout work layered on top of it.
Closeout: Create GitHub issues (if gh available and tracking not already configured)

a. Check gh:
```
gh auth status 2>&1
```
b. If the change already has .github.yaml, skip issue creation.

c. If gh is available and tracking is not yet configured:
- Read proposal.md and tasks.md
- Parse each ## N. Group Name heading in tasks.md and its child checkbox items
- Build one parent issue body with:
  - **Objectives** from the proposal's Why section
  - **Background** from the proposal's What Changes section
  - **Acceptance Criteria** — for each spec file in specs/**/*.md, extract each ### Requirement: name and its first #### Scenario: as a one-line bullet. Format: - **Requirement name**: WHEN condition → THEN outcome
  - **Key Design Decisions** — from design.md, extract each ### N. Decision Title heading and its **Decision:** line as a bullet. Format: - **Decision heading**: decision text. If design.md doesn't exist, omit this section.
  - **Task Groups** table with a Status column:
```
| Group | Name | Issue | Status |
|-------|------|-------|--------|
| 1 | Setup | #<child_1_number> | backlog |
| 2 | Core Implementation | #<child_2_number> | backlog |
```
    All groups start with Status backlog. Status values: backlog → in-progress → review → done.
  - **Progress:** 0/N groups completed
  - **Child Issues** — task list: - [ ] #<number> Group N: name
  - **Conclusion**
  - **References** including the change path
- Create the parent issue:
```
gh issue create --title "feat(<scope>): <change-name>" --body "$PARENT_BODY" --label "backlog"
```
- For each Task Group, build a child issue body using the doc-conv#32 style sections:
  - **Objectives**
  - **Todo**
  - **Estimated Completion Date:** Set when the issue is created
  - **Conclusion**
  - **References** with the parent issue and change path
- Create one child issue per Task Group:
```
gh issue create --title "Group N: <group-name> [<change-name>]" --body "$CHILD_BODY" --label "todo"
```
- Update the parent issue description so its Task Groups table and Child Issues task list includes the created child issue numbers
```
gh issue edit <parent_issue_number> --body "$UPDATED_PARENT_BODY"
```
```
- Save `.github.yaml` in the change directory with the canonical nested tracking contract:
  ```yaml
 parent:
   number: <parent_issue_number>
   url: <parent_issue_url>
 groups:
   - number: 1
     name: "Setup"
     issue_number: <group_1_issue_number>
     url: <group_1_issue_url>
   - number: 2
     name: "Core"
     issue_number: <group_2_issue_number>
     url: <group_2_issue_url>
 ```
 Later phases should treat `.github.yaml` as the canonical local tracking state. Read `parent.number` for the parent issue and match `groups[].number` to each Task Group to find `groups[].issue_number` and `url`.
```
- Post an initial note on the parent issue:
```
gh issue comment <parent_issue_number> --body "Planning complete. This change has one parent issue and one child issue per Task Group. Review the proposal/spec/design/tasks package. After explicit approval, run /corgi-apply to begin implementation."
```
- Update proposal.md in the ## GitHub Issue section with the parent issue link
Closeout: Save worktree metadata (if isolation mode is worktree)

If worktree isolation is active (from Step 2), write .worktree.yaml in the change directory (openspec/changes/<name>/.worktree.yaml):
```
path: .worktrees/<name>
branch: feat/<name>
created: <ISO-8601-timestamp>
```
Also add worktree info to the parent issue. In the parent issue body's References section, include:
```
- Worktree: `.worktrees/<name>` (branch: `feat/<name>`)
```
Update the parent issue description:
```
gh issue edit <parent_issue_number> --body "$UPDATED_PARENT_WITH_WORKTREE"
```
d. If gh is unavailable:
- Print a warning that GitHub issue creation is being skipped
- Do not block artifact creation or readiness for explicit review

Output

After completing all artifacts, summarize:

Change name and location
List of artifacts created with brief descriptions
Handoff status: local artifact package complete
GitHub tracking status: parent issue created or skipped
Worktree status: path and branch (if isolation active), or "none" (if isolation inactive)
Prompt: "Review the proposal/spec/design/tasks package. After explicit approval, run /corgi-apply to start implementation."

Artifact Creation Guidelines

Follow the instruction field from corgispec instructions for each artifact type
The schema defines what each artifact should contain - follow it
Read dependency artifacts for context before creating new ones
Use template as the structure for your output file - fill in its sections
IMPORTANT: context and rules are constraints for YOU, not content for the file
- Do NOT copy <context>, <rules>, <project_context> blocks into the artifact
- These guide what you write, but should never appear in the output

Guardrails

Create ALL artifacts needed for implementation (as defined by schema's apply.requires)
Always read dependency artifacts before creating a new one
If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
Reuse an existing change when appropriate; do not blindly fail on an existing change directory
If .github.yaml already exists, do not create duplicate issues
Verify each artifact file exists after writing before proceeding to next

Successful artifact creation means planning and closeout are complete. It does not replace explicit human review of the proposal/spec/design/tasks package before implementation begins.