dev-config-template

A template for coordinating multi-repo development with OpenSpec and AI assistant (Claude Code) integration.

Why This Template?

When working on projects that span multiple repositories (e.g., a core library + integrations + documentation), you need:

• A central place to coordinate changes across repos
• Consistent AI assistant behavior across the workspace
• Easy setup for new contributors

This template provides that foundation.

Features

• Multi-repo coordination: Manage multiple related repositories in one workspace with centralized configuration
• OpenSpec integration: Structured change management and proposal workflow across repos (via openspec init)
• AI assistant guidance: Pre-configured CLAUDE.md for Claude Code with reasoning framework and coding standards
• One-command setup: Clone all sub-repos with ./script/setup
• Automated initialization: Use the workspace-init skill to set up everything interactively

Quick Start

1. Create from template

Click "Use this template" button on GitHub, or use the CLI:

gh repo create my-workspace --template niracler/dev-config-template --private --clone
cd my-workspace

2. Initialize with Claude Code (recommended)

Run Claude Code and let the workspace-init skill guide you through the full setup:

claude
# Then say: "Help me initialize this workspace" or "帮我初始化工作区"

The skill will interactively:

• Configure repos.json with your sub-repositories
• Customize CLAUDE.md with your role, language, and tech stack
• Clone all sub-repos via script/setup
• Initialize OpenSpec for change management
• Set up dev environments (venv, npm, pre-commit) per repo
• Generate a VSCode workspace file
• Run a validation check to confirm everything is in place

3. Manual setup (alternative)

If you prefer to set things up manually:

Configure your repos -- edit repos.json:

{
  "repos": [
    {
      "name": "my-app",
      "url": "https://github.com/your-org/my-app.git",
      "path": "repos/my-app"
    },
    {
      "name": "my-lib",
      "url": "https://github.com/your-org/my-lib.git",
      "path": "repos/my-lib"
    }
  ]
}

Clone all repos:

./script/setup

Customize CLAUDE.md -- replace the [PLACEHOLDER] tokens with your project details.

Keeping Up to Date

When the template is updated with new features or improvements, use the workspace-init skill's update mode:

claude
# Then say: "Update my workspace template" or "更新工作区模板"

This will detect what changed in the template, show you a diff, and apply structural updates while preserving your customizations (repos.json, filled CLAUDE.md values, OpenSpec config).

File Structure

my-workspace/
├── CLAUDE.md              # AI assistant guidance (customize this!)
├── AGENTS.md -> CLAUDE.md # Symlink for compatibility
├── repos.json             # Sub-repo configuration
├── .gitignore             # Ignores repos/ directory
├── script/
│   └── setup              # Clone script
├── planning/              # Project scheduling (optional)
│   ├── README.md
│   └── schedules/
├── repos/                 # Sub-repos (git-ignored)
│   ├── my-app/
│   └── my-lib/
└── README.md

Optional Extensions

These can be added after initial setup:

VSCode Workspace

Create {project}.code-workspace for multi-root workspace:

{
  "folders": [
    { "path": ".", "name": "Config" },
    { "path": "repos/my-app", "name": "My App" },
    { "path": "repos/my-lib", "name": "My Lib" }
  ]
}

Note: The workspace-init skill generates this automatically during setup.

OpenSpec (Change Management)

OpenSpec provides structured change management for AI-assisted development:

# Install openspec CLI, then:
openspec init

This creates openspec/ directory with:

• Proposal workflow for planning changes
• Spec management for tracking requirements
• Integration with Claude Code slash commands

Note: The workspace-init skill sets up OpenSpec automatically during initialization.

Project Scheduling

The planning/ directory provides lightweight project scheduling with YAML-based schedule files:

claude
# Then say: "planning init my-project"

This creates a schedule YAML in planning/schedules/ that tracks modules, milestones, and delivery phases. See planning/README.md for the full schema.

Note: Requires the workspace-planning skill for programmatic operations (progress review, status updates, Yunxiao sync).

Custom Claude Commands

Add custom slash commands in .claude/commands/:

.claude/
└── commands/
    └── my-command.md

Credits

• CLAUDE.md template based on Xuanwo's AGENTS.md

License

MIT