agentleFS
Sign inStart free
etretr/groundwork/skills/setup-repo/SKILL.md

setup-repo

Skill45 starsChanged 4 days agoMITView on GitHub

This skill should be used when configuring a repository for groundwork - detects single-project or monorepo structure and creates .groundwork.yml

12 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use implement.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Hugging FaceSkill

    implement

    Make tests pass. Invoke after /write-tests produces failing tests.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 6 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Look for common monorepo patterns:

    line 14
  2. Very specific:

    Use AskUserQuestion to confirm:

    line 22
  3. Distinctive:

    If monorepo indicators were found, mention them:

    line 28
  4. Distinctive:

    No config file needed

    line 34
  5. Very specific:

    Ensure .groundwork-plans/, .debug/, and .architecture/ are in .gitignore (add any missing entries) — plan-task, debug, and …

    line 35
  6. Distinctive:

    Ask which directories are projects.

    line 40
  7. Very specific:

    Use AskUserQuestion with multi-select to confirm project list.

    line 41
  8. Very specific:

    Ensure .groundwork.local, .groundwork-plans/, .debug/, and .architecture/ are in .gitignore (add any missing entries).

    line 53
  9. Very specific:

    Ask which project to start with using AskUserQuestion.

    line 54
  10. Distinctive:

    Ask what to add/remove

    line 74
  11. Distinctive:

    Update the config file

    line 75

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Setup Repository Skill

Configures the repository structure for Groundwork. Detects or asks whether this is a single-project repo or a monorepo, and creates .groundwork.yml for monorepos.

Workflow

Step 1: Detect Repository Structure

Look for common monorepo patterns:

  • Multiple directories with their own package.json, go.mod, Cargo.toml, etc.
  • Common monorepo directories: apps/, packages/, services/, projects/
  • Existing specs/ directory (suggests single-project)
  • Workspace configuration files (pnpm-workspace.yaml, lerna.json, turbo.json)

Step 2: Ask User

Use AskUserQuestion to confirm:

"I've analyzed your repo structure. Is this:"

  • Single project — One project, specs at the repo root
  • Monorepo — Multiple projects, each with their own specs

If monorepo indicators were found, mention them:

"I noticed [apps/, packages/, workspace config], which suggests a monorepo structure."

Step 3: Configure

If single project:

  • No config file needed
  • Ensure .groundwork-plans/, .debug/, and .architecture/ are in .gitignore (add any missing entries) — plan-task, debug, and swarm-design-architecture write per-task working files there. All three patterns are unanchored, so they cover any depth.
  • Confirm: "Single-project mode. Specs will be stored in specs/ at the repo root, plans in .groundwork-plans/."
  • Proceed — no .groundwork.yml created.

If monorepo:

  1. Ask which directories are projects. Suggest based on detected structure.
  2. Use AskUserQuestion with multi-select to confirm project list.
  3. Create .groundwork.yml:
version: 1
projects:
  <project-name>:
    path: <relative/path>
  <project-name>:
    path: <relative/path>
  1. Ensure .groundwork.local, .groundwork-plans/, .debug/, and .architecture/ are in .gitignore (add any missing entries). Each project's plans live in <project-path>/.groundwork-plans/ and its journals in <project-path>/.debug/ and <project-path>/.architecture/; the unanchored entries cover every project, so no per-project entries are needed.
  2. Ask which project to start with using AskUserQuestion.
  3. Set project context: GROUNDWORK_PROJECT=<name> and GROUNDWORK_PROJECT_ROOT=<path>

Step 4: Persist Selection

For monorepo mode, persist the selection through the same mechanism /groundwork:select-project uses:

node ${CLAUDE_PLUGIN_ROOT}/lib/persist-project.js "<selected-name>"

This keys state per terminal pane (and pins a per-chat snapshot where hooks observe the selection), so concurrent sessions do not clobber each other. Do not write .groundwork.local by hand — it is a legacy format read only for one-time migration.

Confirm: "Project <name> selected. Specs will be stored in <path>/specs/."

Adding Projects Later

This skill can also be invoked to add or remove projects from an existing .groundwork.yml:

  • Read existing config
  • Present current projects
  • Ask what to add/remove
  • Update the config file

Edge Cases

SituationResponse
.groundwork.yml already existsShow current config, ask if user wants to modify
No obvious project directoriesAsk user to specify paths manually
User says single-project but monorepo indicators existAccept user's choice, note the indicators

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free