@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/workflows/help/modes/topic.md

@@ -0,0 +1,74 @@
+<purpose>
+Emit a section from the full reference for the topic in `$ARGUMENTS`. Read `workflows/help/modes/full.md`, resolve the topic alias to a section heading using the table below, and output the resolved-routing preamble plus the section content. Scope is controlled by a `--brief` flag in `$ARGUMENTS`: full scope (default) emits the entire section; compact scope (`--brief <topic>`) emits only the signature line + one-line summary for a compact scoped lookup. No additions, no surrounding chrome.
+</purpose>
+
+<reference>
+**Topic resolution table.** Match the topic alias case-insensitively. Strip a single leading `--` if present.
+
+| Topic alias(es) | Section heading in `full.md` |
+|---|---|
+| `workflow`, `core`, `core-workflow` | `## Core Workflow` (entire section through end of `### Quick Mode`) |
+| `init`, `new-project` | `### Project Initialization` |
+| `map`, `map-codebase` | The `/gsd:map-codebase` block under `### Project Initialization` |
+| `discuss`, `discuss-phase` | The `/gsd:discuss-phase` block under `### Phase Planning` |
+| `plan`, `planning`, `plan-phase` | `### Phase Planning` |
+| `execute`, `exec`, `execute-phase` | `### Execution` |
+| `progress`, `route` | `### Progress Tracking` plus `### Smart Router` |
+| `quick`, `quick-mode` | `### Quick Mode` |
+| `fast` | The `/gsd:fast` block under `### Quick Mode` |
+| `phase`, `phases`, `roadmap` | `### Roadmap Management` |
+| `milestone`, `milestones` | `### Milestone Management` plus `### Milestone Auditing` |
+| `session`, `pause`, `resume` | `### Session Management` |
+| `debug`, `debugging` | `### Debugging` |
+| `spike` | The `/gsd:spike` and `/gsd:spike --wrap-up` blocks under `### Spiking & Sketching` |
+| `sketch` | The `/gsd:sketch` and `/gsd:sketch --wrap-up` blocks under `### Spiking & Sketching` |
+| `spike-sketch`, `experiments` | `### Spiking & Sketching` |
+| `capture`, `notes`, `todos` | `### Capturing Ideas, Notes, and Todos` |
+| `verify`, `verify-work`, `uat` | `### User Acceptance Testing` plus the `/gsd:audit-uat` block |
+| `ship`, `pr` | `### Ship Work` plus the `/gsd:pr-branch` block |
+| `review`, `peer-review` | The `/gsd:review` block under `### Ship Work` |
+| `audit`, `auditing`, `audit-milestone` | `### Milestone Auditing` |
+| `config`, `settings`, `configuration` | `### Configuration` |
+| `cleanup` | The `/gsd:cleanup` block under `### Utility Commands` |
+| `update` | The `/gsd:update` block under `### Utility Commands` |
+| `files`, `structure`, `layout` | `## Files & Structure` |
+| `modes`, `interactive`, `yolo` | `## Workflow Modes` |
+| `planning-config` | `## Planning Configuration` |
+| `workflows`, `common-workflows`, `examples` | `## Common Workflows` |
+| `help` | `## Getting Help` |
+
+**Output rules:**
+
+1. Parse `$ARGUMENTS`: detect a `--brief` (or `-b`) flag — this selects **compact scope**. Otherwise scope is **full**. Strip the flag, then take the remaining token (with a single leading `--` stripped) as the topic alias.
+2. Resolve the alias against the table.
+3. If no match: emit a one-line error followed by a comma-separated list of the canonical topic names from the leftmost column (one per row, deduplicated). Suggest `/gsd:help --full` for the complete reference. Stop.
+4. If matched: emit a single resolved-routing preamble line so the user sees what was matched:
+
+   ```text
+   **Topic:** `<alias>` → `<heading>` *(scope: full | compact)*
+   ```
+
+   Use the canonical alias from the leftmost column. Use the literal heading text from the matched cell. State the scope you are about to emit.
+
+5. Read `workflows/help/modes/full.md`. Strip `<reference>` / `</reference>` wrapper tags — never emit them. Apply the extraction rule for the matched table cell, modulated by scope:
+
+   5a. **Single section** (cell contains a single `` `## Heading` `` or `` `### Heading` ``):
+   - *Full scope:* emit from that heading up to (but not including) the next sibling or higher-level heading.
+   - *Compact scope:* emit the heading, then the first `` **`/gsd:...`** `` bold line within the section (the signature) and the single non-blank line immediately after it (the one-line summary). If the section has no `` **`/gsd:...`** `` bold line, emit the heading and the first paragraph.
+
+   5b. **Multiple sections joined by "plus"**: apply rule 5a to each listed section in document order and emit them sequentially with no gap between them.
+
+   5c. **Sub-block** (cell says `the /gsd:X block under ### Heading` or `the /gsd:X ... blocks under ### Heading`): within the named heading's section, start at each `` **`/gsd:X ...`** `` bold line.
+   - *Full scope:* stop immediately before the next `` **`/gsd:...`** `` bold line or the next heading, whichever comes first.
+   - *Compact scope:* emit the bold line and the single non-blank line immediately after it (the one-line summary).
+
+   For cells listing multiple sub-blocks, emit them sequentially.
+
+6. After the section content, emit a single closing line:
+
+   ```text
+   More: /gsd:help --full · /gsd:help <topic> · /gsd:help --brief <topic>
+   ```
+
+7. No project-specific commentary, no follow-up questions.
+</reference>

package/get-shit-done/workflows/help.md

@@ -0,0 +1,24 @@
+<purpose>
+Display GSD command help at the tier the user asked for. Output ONLY the reference content of the chosen mode. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
+</purpose>
+
+<progressive_disclosure>
+**Mode files are lazy-loaded.** Read only the one mode file that matches `$ARGUMENTS`, then output its `<reference>` body verbatim.
+
+| When `$ARGUMENTS` is | Read |
+|---|---|
+| `--brief` (or `-b`) alone | `workflows/help/modes/brief.md` |
+| `--full` (or `-f`, `--all`) alone | `workflows/help/modes/full.md` |
+| empty / unset | `workflows/help/modes/default.md` |
+| `--brief <topic>` (or `-b <topic>`) | `workflows/help/modes/topic.md` in compact scope (signature + one-line summary of the matched section) |
+| anything else — bare topic, `--full <topic>`, or topic with leading `--` | `workflows/help/modes/topic.md` in full scope (entire matched section) |
+
+Argument parsing rules:
+- Trim and lowercase `$ARGUMENTS`.
+- Recognize the long form, short form, and obvious aliases listed above.
+- A bare token like `debug`, `--debug`, `capture`, `workflow`, `config` is a topic — route to `topic.md`.
+- Multiple flags: `--brief` and `--full` are mutually exclusive — if both appear *without* a topic, prefer `--full`.
+- `--brief` combined with a topic invokes `topic.md` in compact scope; `--full` combined with a topic invokes `topic.md` in full scope (the default topic behavior). When passing arguments through to `topic.md`, retain the `--brief` flag so the mode can pick the right scope.
+
+After loading the chosen mode, emit its `<reference>` block content directly. No additions, no project context, no suggestions.
+</progressive_disclosure>

package/get-shit-done/workflows/import.md

@@ -0,0 +1,254 @@
+# Import Workflow
+
+External plan ingestion with conflict detection and agent delegation.
+
+- **--from**: Import external plan → conflict detection → write PLAN.md → validate via gsd-plan-checker
+
+Future: `--prd` mode (PRD extraction into PROJECT.md + REQUIREMENTS.md + ROADMAP.md) is planned for a follow-up PR.
+
+---
+
+<step name="banner">
+
+Display the stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► IMPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+</step>
+
+<step name="parse_arguments">
+
+Parse `$ARGUMENTS` to determine the execution mode:
+
+- If `--from` is present: extract FILEPATH (the next token after `--from`), set MODE=plan
+- If `--prd` is present: display message that `--prd` is not yet implemented and exit:
+  ```
+  GSD > --prd mode is planned for a future release. Use --from to import plan files.
+  ```
+- If neither flag is found: display usage and exit:
+
+```
+Usage: /gsd:import --from <path>
+
+  --from <path>   Import an external plan file into GSD format
+```
+
+**Validate the file path:**
+
+Verify the path does not contain traversal sequences and the file exists:
+
+```bash
+case "{FILEPATH}" in
+  *..* ) echo "SECURITY_ERROR: path contains traversal sequence"; exit 1 ;;
+esac
+test -f "{FILEPATH}" || echo "FILE_NOT_FOUND"
+```
+
+If FILE_NOT_FOUND: display error and exit:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+File not found: {FILEPATH}
+
+**To fix:** Verify the file path and try again.
+```
+
+</step>
+
+---
+
+## Path A: MODE=plan (--from)
+
+<step name="plan_load_context">
+
+Load project context for conflict detection:
+
+1. Read `.planning/ROADMAP.md` — extract phase structure, phase numbers, dependencies
+2. Read `.planning/PROJECT.md` — extract project constraints, tech stack, scope boundaries.
+   **If PROJECT.md does not exist:** skip constraint checks that rely on it and display:
+   ```
+   GSD > Note: No PROJECT.md found. Conflict checks against project constraints will be skipped.
+   ```
+3. Read `.planning/REQUIREMENTS.md` — extract existing requirements for overlap and contradiction checks.
+   **If REQUIREMENTS.md does not exist:** skip requirement conflict checks and continue.
+4. Glob for all CONTEXT.md files across phase directories:
+   ```bash
+   find .planning/phases/ -name "*-CONTEXT.md" -o -name "CONTEXT.md" 2>/dev/null
+   ```
+   Read each CONTEXT.md found — extract locked decisions (any decision in a `<decisions>` block)
+
+Store loaded context for conflict detection in the next step.
+
+</step>
+
+<step name="plan_read_input">
+
+Read the imported file at FILEPATH.
+
+Determine the format:
+- **GSD PLAN.md format**: Has YAML frontmatter with `phase:`, `plan:`, `type:` fields
+- **Freeform document**: Any other format (markdown spec, design doc, task list, etc.)
+
+Extract from the imported content:
+- **Phase target**: Which phase this plan belongs to (from frontmatter or inferred from content)
+- **Plan objectives**: What the plan aims to accomplish
+- **Tasks listed**: Individual work items described in the plan
+- **Files modified**: Any files mentioned as targets
+- **Dependencies**: Any referenced prerequisites
+
+</step>
+
+<step name="plan_conflict_detection">
+
+Run conflict checks against the loaded project context. The report format, severity semantics, and safety-gate behavior are defined by `references/doc-conflict-engine.md` — read it and apply it here. Operation noun: `import`.
+
+### BLOCKER checks (any one prevents import):
+
+- Plan targets a phase number that does not exist in ROADMAP.md → [BLOCKER]
+- Plan specifies a tech stack that contradicts PROJECT.md constraints → [BLOCKER]
+- Plan contradicts a locked decision in any CONTEXT.md `<decisions>` block → [BLOCKER]
+- Plan contradicts an existing requirement in REQUIREMENTS.md → [BLOCKER]
+
+### WARNING checks (user confirmation required):
+
+- Plan partially overlaps existing requirement coverage in REQUIREMENTS.md → [WARNING]
+- Plan has `depends_on` referencing plans that are not yet complete → [WARNING]
+- Plan modifies files that overlap with existing incomplete plans → [WARNING]
+- Plan phase number conflicts with existing phase numbering in ROADMAP.md → [WARNING]
+
+### INFO checks (informational, no action needed):
+
+- Plan uses a library not currently in the project tech stack → [INFO]
+- Plan adds a new phase to the ROADMAP.md structure → [INFO]
+
+Render the full Conflict Detection Report using the format in `references/doc-conflict-engine.md`.
+
+**If any [BLOCKER] exists:** apply the safety gate from the reference — exit WITHOUT writing any files. No PLAN.md is written when blockers exist.
+
+**If only WARNINGS and/or INFO (no blockers):**
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+
+Ask via AskUserQuestion using the approve-revise-abort pattern (see `references/gate-prompts.md`):
+- question: "Review the warnings above. Proceed with import?"
+- header: "Approve?"
+- options: Approve | Abort
+
+If user selects "Abort": exit cleanly with message "Import cancelled."
+
+</step>
+
+<step name="plan_convert">
+
+Convert the imported content to GSD PLAN.md format.
+
+Ensure the PLAN.md has all required frontmatter fields:
+```yaml
+---
+phase: "{NN}-{slug}"
+plan: "{NN}-{MM}"
+type: "feature|refactor|config|test|docs"
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+must_haves:
+  truths: []
+  artifacts: []
+---
+```
+
+**Reject PBR naming conventions in source content:**
+If the imported plan references PBR plan naming (e.g., `PLAN-01.md`, `plan-01.md`), rename all references to GSD `{NN}-{MM}-PLAN.md` convention during conversion.
+
+Apply GSD naming convention for the output filename:
+- Format: `{NN}-{MM}-PLAN.md` (e.g., `04-01-PLAN.md`)
+- NEVER use `PLAN-01.md`, `plan-01.md`, or any other format
+- NN = phase number (zero-padded), MM = plan number within the phase (zero-padded)
+
+Determine the target directory by querying `init.phase-op` for the phase number extracted in `plan_read_input`. This ensures the `project_code` prefix from `.planning/config.json` is applied:
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run query init.phase-op "{NN}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+expected_phase_dir=$(echo "$INIT" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).expected_phase_dir)")
+```
+
+If the directory does not exist, create it:
+```bash
+mkdir -p "${expected_phase_dir}"
+```
+
+Set `phase_dir="${expected_phase_dir}"` for use in subsequent steps.
+
+Write the PLAN.md file to the target directory.
+
+</step>
+
+<step name="plan_validate">
+
+Delegate validation to gsd-plan-checker:
+
+```
+Agent({
+  subagent_type: "gsd-plan-checker",
+  prompt: "Validate: .planning/phases/{phase}/{plan}-PLAN.md — check frontmatter completeness, task structure, and GSD conventions. Report any issues."
+})
+```
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
+If the checker returns errors:
+- Display the errors to the user
+- Ask the user to resolve issues before the plan is considered imported
+- Do not delete the written file — the user can fix and re-validate manually
+
+If the checker returns clean:
+- Display: "Plan validation passed"
+
+</step>
+
+<step name="plan_finalize">
+
+Update `.planning/ROADMAP.md` to reflect the new plan:
+- Add the plan to the Plans list under the correct phase section
+- Include the plan name and description
+
+Update `.planning/STATE.md` if appropriate (e.g., increment total plan count).
+
+Commit the imported plan and updated files:
+```bash
+gsd_run query commit "docs({phase}): import plan from {basename FILEPATH}" --files .planning/phases/{phase}/{plan}-PLAN.md .planning/ROADMAP.md
+```
+
+Display completion:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► IMPORT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Show: plan filename written, phase directory, validation result, next steps.
+
+</step>
+
+---
+
+## Anti-Patterns
+
+Do NOT:
+- Violate the shared conflict-engine contract in `references/doc-conflict-engine.md` (no markdown tables, no new severity labels, no bypass of the BLOCKER gate)
+- Write PLAN.md files as `PLAN-01.md` or `plan-01.md` — always use `{NN}-{MM}-PLAN.md`
+- Use `pbr:plan-checker` or `pbr:planner` — use `gsd-plan-checker` and `gsd-planner`
+- Write `.planning/.active-skill` — this is a PBR pattern with no GSD equivalent
+- Reference `pbr-tools`, `pbr:`, or `PLAN-BUILD-RUN` anywhere
+- Write any PLAN.md file when blockers exist — the safety gate must hold
+- Skip path validation on the --from file argument