Skip to content

Workspace initialization should accept existing METHOD signpost aliases #29

Description

@flyingrobots

Migrated from Method backlog

This issue was created from a legacy filesystem backlog card. GitHub Issues are now the live work tracker; repository docs remain Method evidence.

Source backlog: docs/method/backlog/bad-code/PROCESS_workspace-initialization-signpost-aliases.md
Original lane: bad-code
Original legend: PROCESS
Original priority: high

Original backlog card

Workspace Initialization Should Accept Existing METHOD Signpost Aliases

Workspace.ensureInitialized() currently hard-codes the v2 signpost
layout:

CHANGELOG.md
docs/method/backlog/
docs/design/
docs/method/retro/
docs/PROCESS.md
docs/RELEASE.md

That makes MCP tools reject repos that have a valid METHOD filesystem
but use the older or repo-local signpost layout:

docs/METHOD.md
docs/method/process.md
docs/method/release.md

Observed symptom from git-warp:

/Users/james/git/git-stunts/git-warp is not a METHOD workspace.
Run `method init` first.

That repo has a real METHOD backlog, design directory, retro directory,
legends, and process docs. Running method init would be the wrong
advice because it would add generic scaffold signposts instead of
recognizing the existing repo-truth docs.

Required Test Fixture Shape

Write a unit test that creates this exact fixture tree:

workspace/
  CHANGELOG.md
  docs/
    METHOD.md
    design/
      .gitkeep
    method/
      process.md
      release.md
      backlog/
        inbox/
          .gitkeep
        asap/
          .gitkeep
        up-next/
          .gitkeep
        bad-code/
          .gitkeep
        cool-ideas/
          .gitkeep
      retro/
        .gitkeep
      graveyard/
        .gitkeep
      legends/
        .gitkeep

Do not create these files in the fixture:

docs/PROCESS.md
docs/RELEASE.md

The test should assert the existing fixture is accepted:

const workspace = new Workspace(root);

expect(() => workspace.status()).not.toThrow();

If the MCP surface is tested separately, call the same path through
method_status and assert ok: true.

Expected Fix Shape

Make initialization recognition accept either signpost set:

canonical v2:
  docs/PROCESS.md
  docs/RELEASE.md

existing alias layout:
  docs/METHOD.md
  docs/method/process.md
  docs/method/release.md

The shared structural requirements should remain:

CHANGELOG.md
docs/method/backlog/
docs/design/
docs/method/retro/

Do not weaken the workspace check into "any docs directory exists".
This should be a precise compatibility rule for real METHOD workspaces.

Error Message Improvement

When a workspace is truly uninitialized, report the missing paths rather
than only saying:

Run `method init` first.

Useful shape:

<root> is not a METHOD workspace.
Missing required paths:
- docs/method/backlog/
- docs/design/
- docs/method/retro/
Missing one required signpost set:
- docs/PROCESS.md + docs/RELEASE.md
- OR docs/METHOD.md + docs/method/process.md + docs/method/release.md

That lets agents distinguish "run init" from "this repo uses a valid
alternate signpost layout."

Activity

  1. added
    lane:bad-codeKnown debt, rot, or structural risk.
    legend:processMethod process, workflow, adapters, and CLI work.
    type:maintenanceMaintenance, cleanup, or operational workflow work.
    on Jun 1, 2026
  2. coderabbitai commented on Jun 1, 2026

    @coderabbitai
    🔗 Related PRs

    #4 - Split CLI into behavior-owned modules and close out cycle 0007 [merged]
    #5 - Shape release workflow and user migration docs [merged]
    #6 - Automated Witness Capture (Cycle 0020) [merged]
    #12 - Configurable Workspace Paths (Cycle 0025) [merged]
    #22 - Add doctor command [merged]


    📝 Issue Planner

    Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.

    • Create Plan

    🧪 Issue enrichment is currently in open beta.

    You can configure auto-planning by selecting labels in the issue_enrichment configuration.

    To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

    issue_enrichment:
      auto_enrich:
        enabled: false

    💬 Have feedback or questions? Drop into our discord!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    lane:bad-codeKnown debt, rot, or structural risk.legend:processMethod process, workflow, adapters, and CLI work.priority:highHigh priority.type:maintenanceMaintenance, cleanup, or operational workflow work.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions