Skip to content

[Chore] Default the split-portfolio sibling repo name to <fork>-portfolio #163

@atlas-apex

Description

@atlas-apex

Driver

The split-portfolio mode (docs/multi-project.md) currently recommends your-org/ops as the default name for the private sibling repo, and portfolio/ as the local clone directory. Both are too generic:

  • your-org/ops doesn't say which framework / which fork the portfolio belongs to. An adopter running multiple ops setups (e.g. one ApexYard fork for product, one for platform) ends up with your-org/ops collisions or has to invent custom names ad-hoc each time.
  • portfolio/ as a local sibling dir gives no signal about which framework's portfolio it is when listed in ~/Projects/. Mixed with other unrelated portfolio/ dirs from other tooling, the namespace muddles fast.

<fork-name>-portfolio makes the relationship explicit and self-documenting on disk and on GitHub. If the fork is your-org/apexyard, the portfolio defaults to your-org/apexyard-portfolio and the local sibling defaults to apexyard-portfolio/. If the fork was renamed (your-org/cos), the portfolio defaults to your-org/cos-portfolio.

Surfaced during a fresh-fork /setup test on 2026-05-03 — the proposed plan offered your-org/ops and the user redirected to "make the 2nd dir apexyard-portfolio, name the GitHub repo the same."

Scope

Prose / example-only changes — no mechanism changes. Files affected:

  • docs/multi-project.md — every example in the split-portfolio mode section that uses your-org/ops, ~/ops/portfolio/, or generic portfolio/ updated to the new <fork>-portfolio naming. Includes the directory-layout diagrams, the step-by-step walkthrough, and the FAQ.
  • .claude/skills/setup/SKILL.md — Step 2b (split-portfolio path) currently proposes your-org/ops; flip to suggesting <fork>-portfolio (resolve the fork name dynamically).
  • .claude/skills/split-portfolio/SKILL.md — the migration helper currently defaults to creating your-org/ops as the new private repo; flip to <fork>-portfolio. The path-resolution helper stays sibling-of-the-fork by convention.
  • apexyard.projects.yaml.example — verify. If the example carries a registry-name comment that references the convention, update it.

Acceptance Criteria

  • grep -rn "your-org/ops\|~/ops/" docs/ .claude/skills/ returns 0 matches in non-historical files (AgDRs may keep historical references; they're decision records, not configuration).
  • /setup Step 2b's proposed default for the private repo name is <fork>-portfolio (computed from the fork's repo name, not hardcoded).
  • /split-portfolio migration helper proposes <fork>-portfolio as the new private repo name in step 1 (create-the-private-repo).
  • Both skills make clear in their prose that the name is overridable — <fork>-portfolio is just the suggestion, not a requirement.
  • docs/multi-project.md directory-layout diagrams use the new naming consistently.
  • No mechanism change — adopters with existing ops/ setups continue to work because the config block in .claude/project-config.json resolves whatever path they configured.

Risks / Dependencies

  • No mechanism change. The portfolio: config block in .claude/project-config.json already takes any path — this PR just changes the prose suggestions. Existing adopters who set up ops/ are unaffected.
  • Fresh-fork adopters who haven't read the new docs will still see whatever was the current convention at fork-time; /update brings them the new default on their next sync.
  • No test coverage required — the changes are documentation prose. The skill files have no automated test today (skills are markdown instructions).

Refs: surfaced during /setup fresh-fork testing on 2026-05-03.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium — plan-worthy, not urgent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions