3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
5.5 KiB
How to migrate from GSD-2
Goal: Bring an older GSD-2 project (.gsd/ directory layout) forward into GSD Core (.planning/ layout), and optionally absorb any existing ADRs, PRDs, or specs that live in the repository into the new planning structure.
Prerequisites: GSD Core is installed. The GSD-2 project directory is available on disk.
Understand what migrates
GSD-2 used a .gsd/ directory as its planning root. GSD Core uses .planning/. The migration reverses this: it reads .gsd/ artifacts and writes them into the standard .planning/ structure that all GSD Core commands expect.
| What exists in GSD-2 | What /gsd-import --from-gsd2 produces |
|---|---|
.gsd/PROJECT.md |
.planning/PROJECT.md |
.gsd/ROADMAP.md |
.planning/ROADMAP.md |
.gsd/STATE.md |
.planning/STATE.md |
.gsd/phases/ directories |
.planning/phases/ directories |
Phase PLAN.md files |
GSD Core {NN}-{MM}-PLAN.md files (renaming enforced) |
Conflict detection runs before any files are written. If the target directory already has a PROJECT.md and the imported content contradicts it, the migration stops at the BLOCKER gate and lists the conflicts for you to resolve.
Run the migration
Migrate the current directory
/gsd-import --from-gsd2
GSD reads .gsd/ in the current working directory and writes the migrated artifacts into .planning/.
Migrate from a different path
/gsd-import --from-gsd2 --path ~/projects/old-project
Use --path when the GSD-2 project is not your current working directory.
Resolve conflicts
If conflict detection finds blockers — for example, a GSD-2 tech-stack declaration that contradicts an existing .planning/PROJECT.md — it prints a conflict report and stops without writing any files.
Read the report, resolve the contradiction (edit the source document or the existing planning artifact), then re-run /gsd-import --from-gsd2. The migration is safe to re-run until it passes cleanly.
Import an external plan file
If you have a standalone plan document (a team planning document, a Markdown spec, an exported task list) rather than a full GSD-2 project, use --from instead:
/gsd-import --from /tmp/team-plan.md
GSD performs the same conflict-detection pass, converts the content to GSD Core PLAN.md format, and validates the result with the plan-checker. After validation you will see the target filename and next steps.
Absorb existing documentation
If your repository already contains ADRs (Architecture Decision Records), PRDs, or specification documents, use /gsd-ingest-docs to synthesise them into the .planning/ structure after migration:
Scan the whole repository (auto-detects mode)
/gsd-ingest-docs
If .planning/ is already present (for example, from the migration you just ran), GSD defaults to merge mode — it synthesises the ingested documents alongside what is already there rather than overwriting it.
Scope to a specific directory
/gsd-ingest-docs docs/
/gsd-ingest-docs docs/adr/
Use an explicit precedence manifest
When documents have mixed types or you want to control which document wins on conflicts:
/gsd-ingest-docs --manifest ingest.yaml
The manifest is a YAML file listing {path, type, precedence?} per document. See the --manifest flag description in Commands for the expected shape.
Force a specific mode
/gsd-ingest-docs --mode merge # Merge into existing .planning/
/gsd-ingest-docs --mode new # Bootstrap from scratch (overwrites)
Output: /gsd-ingest-docs always produces an INGEST-CONFLICTS.md with three buckets — auto-resolved, competing-variants, and unresolved-blockers. Review this file after every ingest run. Hard-stops only occur on LOCKED-vs-LOCKED ADR contradictions; everything else is surfaced for your review, not silently discarded.
Verify the migrated project
Once migration and any doc ingestion are complete, confirm the project state is consistent:
/gsd-health
/gsd-health --repair
/gsd-health checks .planning/ directory integrity and reports any drift. --repair auto-fixes recoverable issues.
Then check that GSD Core can read your project state:
/gsd-progress
If the project came across cleanly you will see the current phase status and the recommended next step. From here the standard GSD Core workflow applies.
Conditionals: what migrates and what does not
| Situation | What to do |
|---|---|
.gsd/ exists in the current directory |
Run /gsd-import --from-gsd2 (no --path needed) |
.gsd/ is in a different directory |
Use --path ~/projects/old-project |
| You have a standalone plan document, not a full GSD-2 project | Use /gsd-import --from /path/to/plan.md |
You have ADRs in docs/adr/ |
Run /gsd-ingest-docs docs/adr/ after migration |
| You have a mix of ADRs, PRDs, and specs | Run /gsd-ingest-docs at repo root; it classifies automatically |
| Conflict detection reports blockers | Resolve the listed contradictions then re-run; no files are written until all blockers clear |
| You are not sure whether migration worked | Run /gsd-health and /gsd-progress to confirm |
| INGEST-CONFLICTS.md lists unresolved blockers | These require manual resolution before affected documents are incorporated into planning |