From 57e697c0973d716bd14f01058e8ea4a145bd2b40 Mon Sep 17 00:00:00 2001
From: Jiang Bohan <bhjiang@outlook.com>
Date: Wed, 1 Apr 2026 15:56:23 +0800
Subject: [PATCH] feat: add dev-workflow skill for agent PR workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a Claude Code skill that teaches agents the two-stage PR process:
feature branch → dev (staging) → main (production).
---
 .claude/skills/dev-workflow.md | 72 ++++++++++++++++++++++++++++++++++
 .gitignore                     |  3 +-
 2 files changed, 74 insertions(+), 1 deletion(-)
 create mode 100644 .claude/skills/dev-workflow.md

diff --git a/.claude/skills/dev-workflow.md b/.claude/skills/dev-workflow.md
new file mode 100644
index 000000000..c54594fb8
--- /dev/null
+++ b/.claude/skills/dev-workflow.md
@@ -0,0 +1,72 @@
+---
+description: Multica development workflow — branch management, PR creation, and deployment process. Use after completing a feature or fix to create the correct PRs.
+user_invocable: true
+---
+
+# Multica Development Workflow
+
+## Branch Strategy
+
+| Branch | Environment | URL |
+|--------|-------------|-----|
+| `main` | Production | https://multica.ai |
+| `dev` | Staging/Testing | https://multica-app.copilothub.ai |
+
+Feature branches are created from `dev` (or `main`) and merged through a two-stage PR process.
+
+## After Completing Your Work
+
+### Step 1: Create PR to `dev`
+
+Create a pull request targeting the `dev` branch for staging deployment and testing.
+
+```bash
+gh pr create --base dev --title "<conventional title>" --body "$(cat <<'EOF'
+## Summary
+<describe changes>
+
+## Test plan
+<how to verify>
+EOF
+)"
+```
+
+Post the PR link as a comment on your issue so the team knows it's ready for review.
+
+### Step 2: Wait for staging verification
+
+After the PR to `dev` is merged and deployed to https://multica-app.copilothub.ai, the team will verify the changes on staging. Do **not** proceed to step 3 until staging verification is confirmed.
+
+### Step 3: Create PR to `main`
+
+Once staging is verified, create a second pull request to merge your feature branch into `main` for production deployment.
+
+```bash
+gh pr create --base main --title "<conventional title>" --body "$(cat <<'EOF'
+## Summary
+<describe changes>
+
+Staging PR: <link to dev PR>
+
+## Test plan
+Verified on staging: https://multica-app.copilothub.ai
+EOF
+)"
+```
+
+## PR Title Format
+
+Follow conventional commit format for PR titles:
+- `feat(scope): description` — new feature
+- `fix(scope): description` — bug fix
+- `refactor(scope): description` — code refactor
+- `docs: description` — documentation
+- `test(scope): description` — tests
+- `chore(scope): description` — maintenance
+
+## Checklist
+
+Before creating any PR:
+1. Ensure your branch is pushed to remote: `git push -u origin <branch>`
+2. Run relevant checks (`make check` or subset)
+3. Target `dev` first, never push directly to `main`
diff --git a/.gitignore b/.gitignore
index b5e1c38a6..802f9b873 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,7 +35,8 @@ apps/web/test-results/
 .context
 
 # local settings
-.claude/
+.claude/*
+!.claude/skills/
 
 # feature tracking
 _features/