From b123d415906d0d37013df497596defefa8715902 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Tue, 19 May 2026 18:49:33 -0400 Subject: [PATCH] docs: sync agent guide with AGENTS --- CLAUDE.md | 611 ++++++++---------------------------------------------- 1 file changed, 86 insertions(+), 525 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cbdc918a..9d900563 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,563 +1,124 @@ -# Agent Guidelines +# CCS CLI Agent Guide -AI-facing guidance for agent tooling when working with this repository. +Canonical agent instructions for `/Users/kaitran/CloudPersonal/ccs/cli`. +`AGENTS.md` must stay a symlink to this file. -## Critical Constraints (NEVER VIOLATE) +## Scope -### Test Isolation (MANDATORY) +CCS is a TypeScript/Bun CLI and dashboard for managing Claude Code, Codex, +Factory Droid, CLIProxy, and compatible provider profiles. -**NEVER touch the user's real `~/.ccs/` or `~/.claude/` directories during tests.** +## Non-Negotiables -- All code accessing CCS paths MUST use `getCcsDir()` from `src/utils/config-manager.ts` -- This function respects `CCS_HOME` env var for test isolation -- **WRONG:** `path.join(os.homedir(), '.ccs', ...)` -- **CORRECT:** `path.join(getCcsDir(), ...)` +- Default branch is `dev`. Feature/fix branches start from `dev`; production + hotfixes start from `main` only when explicitly needed. +- Never touch the user's real `~/.ccs/` or `~/.claude/` in tests. Use + `getCcsDir()` from `src/utils/config-manager.ts`; it respects `CCS_HOME`. +- Do not commit directly to `dev` or `main`. +- Do not manually bump versions or create release tags. Semantic-release owns + versions, changelog, tags, npm publish, and GitHub releases. +- CLI terminal output must be ASCII only: `[OK]`, `[!]`, `[X]`, `[i]`. +- Respect `NO_COLOR` and TTY-aware output. -Tests set `process.env.CCS_HOME` to a temp directory. Code using `os.homedir()` directly will modify the user's real files. +## Architecture -## CI-First Protocol (MANDATORY) +- `src/` - TypeScript CLI/server source. +- `lib/ccs`, `lib/ccs.ps1` - bootstrap wrappers; no help text here. +- `ui/src/` - React dashboard. +- `dist/` and `dist/ui/` - build outputs. +- `docs/` - local development and architecture docs. +- Docker support lives under `docker/` and related commands. -**A task is NOT complete until CI is green. After every `git push`, the AI agent MUST block on CI until it passes.** +Profile resolution priority: -### Required Sequence -1. `git push` -2. **Immediately** run `gh pr checks --watch` (or `gh run watch`) and block until all checks complete. -3. If **green** → task may proceed to next step / be declared done. -4. If **red**: - - Pull failing logs: `gh run view --log-failed` (or `gh pr checks ` to identify the failing job, then `gh run view --log-failed`). - - Fix the root cause locally. Do NOT retry blindly. - - Commit and push again. Re-watch CI. -5. Applies to initial `gh pr create` AND every subsequent push on an open PR. +1. Built-in CLIProxy providers: Gemini, Codex, Antigravity. +2. User-defined `config.cliproxy` providers. +3. Settings-based `config.profiles`. +4. Account-based `profiles.json` with isolated `CLAUDE_CONFIG_DIR`. -### Fallback (when `--watch` is unavailable or flaky) -Poll with short sleep until no check is `pending` / `in_progress`: -```bash -until [ "$(gh pr checks --json state -q '[.[] | select(.state == "IN_PROGRESS" or .state == "PENDING" or .state == "QUEUED")] | length')" = "0" ]; do - sleep 10 -done -gh pr checks -``` +All env values written into settings must be strings. -### Absolute rule -AI MUST NOT declare a task done, close a session, or move to the next task while CI is red or still running. Leaving a PR red and moving on is the primary failure mode this protocol prevents. +## User-Facing Change Checklist -### Dev Release vs Push CI +- Update the matching `--help` handler when CLI behavior changes. +- Keep README concise; do not remove `## Community Projects` or + `## Star History` unless explicitly asked. +- Use neutral broad examples such as `ccs`, `ccs codex`, `ccs glm`, or + `ccs ` unless the page is provider-specific. +- If CLI commands, config, providers, install steps, or user workflows change, + update the public CCS docs in `/Users/kaitran/CloudPersonal/ccs/docs`. -- `CI` is the pull-request quality gate for contributor branches. -- `Push CI` is the post-merge quality signal for `dev`. -- `Dev Release` publishes the `@dev` package after `dev` changes land. -- A red `Dev Release` does **not** automatically mean contributor code failed. Check `Push CI` first. -- Verified on `2026-04-22` via `gh api repos/kaitranntt/ccs/branches/dev/protection`: `dev` currently requires `typecheck`, `lint`, `format`, `build`, and `test`, has no branch restrictions, and has no required PR-review gate. -- `dev-release.yml` currently pushes with `PAT_TOKEN` because `dev` is protected by those required status checks. Do not switch it back to `github.token` unless branch protection changes with it. +Help locations: -### Self-Hosted Runner Policy +- `ccs --help`: `src/commands/help-command.ts` +- `ccs api --help`: `src/commands/api-command.ts` +- `ccs cleanup --help`: `src/commands/cleanup-command.ts` +- `ccs cliproxy --help`: `src/commands/cliproxy-command.ts` +- `ccs config --help`: `src/commands/config-command.ts` +- `ccs copilot --help`: `src/commands/copilot-command.ts` +- `ccs cursor --help`: `src/commands/cursor-command.ts` +- `ccs doctor --help`: `src/commands/doctor-command.ts` +- `ccs docker --help`: `src/commands/docker/help-subcommand.ts` +- `ccs env --help`: `src/commands/env-command.ts` +- `ccs migrate --help`: `src/commands/migrate-command.ts` +- `ccs persist --help`: `src/commands/persist-command.ts` +- `ccs setup --help`: `src/commands/setup-command.ts` -- Keep active CCS workflows on local self-hosted runners by default. Do **not** move jobs to `ubuntu-latest`, `macos-latest`, or other GitHub-hosted runners as the first security fix. -- For this public repo, standard GitHub-hosted runners may not consume billable minutes, but the project policy is still local-runner-first to keep compute predictable and avoid future quota surprises across repos. -- Make self-hosted use secure by gating untrusted PR triggers, avoiding checkout of untrusted code in privileged `pull_request_target` jobs, setting `persist-credentials: false`, and scoping PAT-backed credentials to the exact release/sync push step. -- If a workflow truly needs GitHub-hosted runners, document the exception in this file and add a regression test for the exception. +## Validation -## Core Function - -Multi-provider profile and runtime manager for Claude Code, Factory Droid, -Codex CLI, and other compatible targets. See README.md for user documentation. - -## README Preservation - -When editing `README.md`, keep the file concise and funnel detailed usage into -the docs site, but **do not remove the `## Community Projects` section** or the -`## Star History` section unless the user explicitly asks for those sections to -be deleted. Treat both as protected README content. - -When a contributor adds a useful community integration section to `README.md`, -prefer preserving the attribution in `## Community Projects` and moving the -setup substance into a docs page, rather than deleting the contribution. - -Outside provider-specific Gemini and Antigravity docs, avoid using `ccs gemini` -or `ccs agy` as the primary hero example, default starter route, or generic -workflow example. Prefer `ccs`, `ccs codex`, `ccs kiro`, `ccs glm`, Droid -examples, or neutral `ccs ` placeholders when the page is about a -broader topic. - -## Design Principles (ENFORCE STRICTLY) - -### Technical Excellence -- **YAGNI**: No features "just in case" -- **KISS**: Simple bash/PowerShell/Node.js only -- **DRY**: One source of truth (config.yaml) - -### User Experience (EQUALLY IMPORTANT) -- **CLI-Complete**: All features MUST have CLI interface -- **Dashboard-Parity**: Configuration features MUST also have Dashboard interface -- **Execution is CLI**: Running profiles happens via terminal, not dashboard buttons -- **UX > Brevity**: Error messages and help text prioritize user success over terseness -- **Progressive Disclosure**: Simple by default, power features accessible but not overwhelming - -### When Principles Conflict -- **UX > YAGNI** for user-facing features (if users need it, it's not "just in case") -- **KISS applies to BOTH** code AND user experience (simple journey, not just simple code) -- **DRY applies to BOTH** code AND interface patterns (consistent behavior across CLI/Dashboard) - -## Common Mistakes (AVOID) - -| Mistake | Consequence | Correct Action | -|---------|-------------|----------------| -| Running `validate` without `format` first | format:check fails | Run `bun run format` BEFORE validate | -| Treating `Dev Release` as the contributor quality signal | Publish failures on `dev` look like broken code | Check PR `CI` on the branch and `Push CI` on `dev` first | -| Using `chore:` for dev→main PR | No npm release triggered | Use `feat:` or `fix:` prefix | -| Committing directly to `main` or `dev` | Bypasses CI/review | Always use PRs | -| Manual version bump or git tag | Conflicts with semantic-release | Let CI handle versioning | -| Forgetting `--help` update | CLI docs out of sync | Update `src/commands/help-command.ts` | -| Forgetting docs update | User docs out of sync | Update `docs/` and CCS docs submodule | - -## GitHub Issue Operations (CCS-Specific) - -These rules apply when the task is issue triage, backlog cleanup, labels, comments, Projects, or milestones for this repo. - -### Scope Boundary - -- Treat issue triage as a **GitHub-only workflow** unless the user explicitly asks for implementation. -- Do **NOT** create a worktree, branch, PR, or run `/fix`, `/cook`, or `kai:maintainer` just to tag issues, post follow-up comments, close duplicates, or clean up backlog state. -- Escalate into code workflow only when: - - the user explicitly asks to fix/implement an issue, or - - triage proves the same task now requires code changes. - -### Read Before Mutating - -- Always inspect live issue state first with `gh issue view --json ...` or `gh api`. -- Never rely on stale memory, screenshots, or issue titles alone. -- Before closing as resolved, cross-check repo evidence in at least one of: - - `README.md` - - `docs/` - - `CHANGELOG.md` - - relevant source/help handlers -- If the `gh` query would touch Projects fields, verify token scope first. Missing `read:project` is a real blocker, not something to hand-wave around. - -### Labeling Standard - -- Every **open** issue should end triage with: - - one primary type label: `bug`, `enhancement`, `question`, `documentation`, `duplicate`, `invalid`, or `wontfix` - - one area label: - - `area:cli-runtime` - - `area:dashboard-ui` - - `area:config-auth` - - `area:provider-integration` - - `area:install-packaging` - - `area:documentation` - - `area:contributor-workflow` -- Add routing labels only when they materially change handling: - - `upstream-blocked` - - `needs-repro` - - `needs-split` - - `docs-gap` -- Use release-state labels for shipped work: - - `pending-release` - - `released-dev` - - `released` -- Do **NOT** create or use status labels like `todo`, `doing`, `blocked`, `done`. -- Do **NOT** create provider-name labels unless there is a proven long-term need. Provider names belong in titles/issues, not label spam. - -### Commenting Rules - -- Keep issue comments short, technical, and neutral. -- State the decision plainly: close, keep open, retag, needs repro, duplicate, blocked upstream. -- Include exact evidence when relevant: version, doc path, changelog release, canonical issue, upstream link. -- Do **NOT** reference internal plans, local report files, agent prompts, or private reasoning. -- Post **one** maintainer follow-up comment per triage pass. If accidental duplicates are created, delete them with `gh api repos///issues/comments/ -X DELETE`. - -### Closure Rules - -- Close immediately when: - - the issue is an obvious duplicate and you can point to the canonical issue - - the feature/fix is clearly shipped and documented - - a previously `pending-release` issue is now clearly past release and no longer needs tracking -- Keep open and retag when: - - upstream dependency still blocks CCS adoption -> `upstream-blocked` - - latest-release behavior is unclear -> `needs-repro` - - issue contains multiple independent asks -> `needs-split` - - feature likely exists but discoverability/docs are weak -> `docs-gap` -- Do **NOT** close just because an issue is old, vague, or inconvenient. Close only with evidence. - -### Projects And Milestones - -- Preferred project model for this repo: one project, `CCS Backlog`. -- Use Projects for workflow state and priority. Use labels for meaning and routing. -- Milestones are for real ship windows only, not generic categorization buckets. -- If `gh` token lacks `read:project`, say so explicitly and stop short of pretending Projects data is available. -- Active project: - - owner: `kaitranntt` - - number: `3` - - URL: `https://github.com/users/kaitranntt/projects/3` -- Active project fields: - - `Status` -> use for work state (`Todo`, `In Progress`, `Done`) - - `Priority` -> `P1` for bugs, `P2` default backlog, `P3` for broad `needs-split` buckets unless explicitly reprioritized - - `Follow-up` -> `Ready`, `Needs repro`, `Blocked upstream`, `Needs split`, `Docs follow-up` - - `Next review` -> date only for issues that need a follow-up checkpoint -- When triaging an open issue, make sure it exists in `CCS Backlog` and the project fields match the routing labels. -- Do **NOT** create a second backlog project unless the user explicitly wants a project split and gives a reason. -- Current automation path: - - workflow file: `.github/workflows/sync-ccs-backlog-project.yml` - - sync script: `scripts/github/ccs-backlog-sync.mjs` - - required Actions secret: `CCS_PROJECT_AUTOMATION_TOKEN` -- Automation mapping must stay aligned with labels: - - `upstream-blocked` -> `Follow-up=Blocked upstream` - - `needs-repro` -> `Follow-up=Needs repro` - - `needs-split` -> `Follow-up=Needs split` - - `docs-gap` -> `Follow-up=Docs follow-up` - - otherwise -> `Follow-up=Ready` - -### New Or Updated Issue Creation - -- When creating issues for this repo: - - assign `@kaitranntt` - - use conventional issue titles: `bug: ...`, `feat: ...`, `docs: ...` - - keep bodies factual and technical - - avoid personal info and internal-only context - -## Quality Gates (MANDATORY) - -Quality gates MUST pass before pushing. **Both projects have identical workflow.** - -### Pre-Commit Sequence (FOLLOW THIS ORDER) +Format before validating: ```bash -# Main project (from repo root) -bun run format # Step 1: Fix formatting -bun run lint:fix # Step 2: Fix lint issues -bun run validate # Step 3: Fast gate (typecheck + lint + format + test:fast) -bun run validate:ci-parity # Step 4: PR-CI parity gate (branch check + build + full tests + e2e) - -# UI project (if UI changed) -cd ui -bun run format # Step 1: Fix formatting -bun run lint:fix # Step 2: Fix lint issues -bun run validate # Step 3: Final check (must pass) +cd /Users/kaitran/CloudPersonal/ccs/cli && bun run format +cd /Users/kaitran/CloudPersonal/ccs/cli && bun run lint:fix +cd /Users/kaitran/CloudPersonal/ccs/cli && bun run validate ``` -**WHY THIS ORDER:** -- `validate` runs `format:check` which only VERIFIES—won't fix -- If format:check fails, you skipped step 1 -- `validate` now uses read-only `lint`, so autofix still belongs in step 2 -- PR CI and `validate:ci-parity` both run non-mutating checks only +Before requesting review or merge, run: -### What Each Gate Runs - -| Project | Command | Runs | -|---------|---------|------| -| Main | `bun run validate` | typecheck + lint + format:check + test:fast | -| Main | `bun run validate:ci-parity` | base branch check + typecheck + lint + format:check + build:all + test:all + test:e2e | -| UI | `bun run validate` | typecheck + lint:fix + format:check | - -### ESLint Rules (ALL errors) - -| Rule | Level | Notes | -|------|-------|-------| -| `@typescript-eslint/no-unused-vars` | error | Ignore `_` prefix | -| `@typescript-eslint/no-explicit-any` | error | Use proper types or `unknown` | -| `@typescript-eslint/no-non-null-assertion` | error | No `!` assertions | -| `prefer-const`, `no-var`, `eqeqeq` | error | Code quality | -| `react-hooks/*` (UI only) | recommended | Hooks rules | -| `react-refresh/*` (UI only) | vite | Fast refresh | - -### TypeScript Options (strict mode) - -| Option | Value | Notes | -|--------|-------|-------| -| `strict` | true | All strict flags enabled | -| `noUnusedLocals` | true | No unused variables | -| `noUnusedParameters` | true | No unused params | -| `noImplicitReturns` | true | All paths must return | -| `noFallthroughCasesInSwitch` | true | Explicit case handling | - -### Automatic Enforcement - -- `prepack` runs `build:all` -- PR `CI` runs `typecheck`, `lint`, `format`, `build`, `test:all`, and `test:e2e` -- `Push CI` runs the same quality suite on `dev` after merge, separate from release publishing -- `Dev Release` still runs build + fast validation + slow tests + e2e before publishing and still requires `PAT_TOKEN` to push back to protected `dev` -- husky `pre-commit` runs quick lint/type/format checks -- husky `pre-push` runs the full `bun run validate:ci-parity` gate on `main`/`dev`/hotfix branches -- husky `pre-push` runs a faster feature-branch gate (`typecheck` + `lint` + `format:check` + `test:fast`) plus targeted checks based on changed files - -### Maintainability Gate Status - -- The historical maintainability baseline gate is retired from the active CCS workflow. -- `validate`, `validate:ci-parity`, PR `CI`, `Push CI`, and release workflows do **not** invoke `maintainability:check`. -- Older roadmap references to `maintainability:baseline` / `maintainability:check` are historical context, not current repo commands. - -## Critical Constraints (NEVER VIOLATE) - -1. **NO EMOJIS in CLI output** - Terminal output uses ASCII only: [OK], [!], [X], [i] - - **Scope:** CCS CLI terminal output (`src/` code that prints to stdout/stderr) - - **Does NOT apply to:** PR descriptions, commit messages, documentation, comments, AI conversations -2. **TTY-aware colors** - Respect NO_COLOR env var -3. **Non-invasive** - NEVER modify external tool settings (`~/.claude/settings.json`) without explicit user request and confirmation (exception: `ccs persist` command) -4. **Cross-platform parity** - bash/PowerShell/Node.js must behave identically -5. **CLI documentation** - ALL CLI changes MUST update respective `--help` handler (see table below) -6. **Idempotent** - All install operations safe to run multiple times -7. **Dashboard parity** - Configuration features MUST work in both CLI and Dashboard - -### Help Location Reference - -| Command | Help Handler Location | -|---------|----------------------| -| `ccs --help` | `src/commands/help-command.ts` | -| `ccs api --help` | `src/commands/api-command.ts` → `showHelp()` | -| `ccs cleanup --help` | `src/commands/cleanup-command.ts` → `printHelp()` | -| `ccs cliproxy --help` | `src/commands/cliproxy-command.ts` → `showHelp()` | -| `ccs config --help` | `src/commands/config-command.ts` → `showHelp()` | -| `ccs copilot --help` | `src/commands/copilot-command.ts` → `handleHelp()` | -| `ccs cursor --help` | `src/commands/cursor-command.ts` → `handleHelp()` | -| `ccs doctor --help` | `src/commands/doctor-command.ts` → `showHelp()` | -| `ccs docker --help` | `src/commands/docker/help-subcommand.ts` → `showHelp()` | -| `ccs migrate --help` | `src/commands/migrate-command.ts` → `printMigrateHelp()` | -| `ccs env --help` | `src/commands/env-command.ts` → `showHelp()` | -| `ccs persist --help` | `src/commands/persist-command.ts` → `showHelp()` | -| `ccs setup --help` | `src/commands/setup-command.ts` → `showHelp()` | - -**Note:** `lib/ccs` and `lib/ccs.ps1` are bootstrap wrappers only—they delegate to Node.js and contain no help text. - -## Documentation Requirements (MANDATORY) - -**Documentation is a first-class citizen. ALL user-facing changes require docs updates.** - -### Local Documentation (`docs/`) - -Update local `docs/` folder for: -- Architecture changes -- Internal API documentation -- Development guides - -### CCS Docs Submodule (Owner Only) - -**For @kaitranntt (repository owner):** When adding/changing CLI commands or config options, you MUST also update the CCS docs submodule at `~/CloudPersonal/ccs/docs/`: - -| Change Type | Files to Update | -|-------------|-----------------| -| New CLI command/flag | `reference/cli-commands.mdx` | -| New config option | `reference/config-schema.mdx` | -| Provider feature | `providers/.mdx` | -| New feature | `features/.mdx` | - -**Workflow for docs submodule:** ```bash -cd ~/CloudPersonal/ccs/docs/ -git checkout main && git pull -# Make changes -git add -A && git commit -m "docs: " -git push origin main +cd /Users/kaitran/CloudPersonal/ccs/cli && bun run validate:ci-parity ``` -**For external contributors:** Document changes in PR description. Owner will sync to CCS docs. +If UI changed: -### Pre-Commit Docs Checklist - -- [ ] Respective `--help` updated (see Help Location Reference table) -- [ ] Local `docs/` updated if architecture changed -- [ ] CCS docs submodule updated (owner) or PR description includes docs (contributor) - -## Feature Interface Requirements - -| Feature Type | CLI | Dashboard | Example | -|--------------|-----|-----------|---------| -| Profile creation | ✓ | ✓ | `ccs auth create`, Dashboard "Add Account" | -| Profile switching | ✓ | ✓ | `ccs ` (execution is CLI-only) | -| API key config | ✓ | ✓ | `ccs api create`, Dashboard API Profiles | -| Health check | ✓ | ✓ | `ccs doctor`, Dashboard Live Monitor | -| OAuth auth flow | ✓ | ✓ | Browser opens from CLI or Dashboard | -| Analytics/monitoring | ✗ | ✓ | Dashboard Analytics (visual by nature) | -| WebSearch config | ✓ | ✓ | CLI flags, Dashboard Settings | -| Remote proxy config | ✓ | ✓ | CLI flags, Dashboard Settings | - -## File Structure - -``` -src/ → TypeScript source (main project) -dist/ → Compiled JavaScript (npm package) -lib/ → Native shell scripts (bash, PowerShell) -ui/src/ → React components, hooks, pages -ui/src/components/ui/ → shadcn/ui components -dist/ui/ → Built UI bundle (served by Express) -``` - -## Key Technical Details - -### Profile Mechanisms (Priority Order) - -1. **CLIProxy hardcoded**: gemini, codex, agy → OAuth-based, zero config -2. **CLIProxy variants**: `config.cliproxy` section → user-defined providers -3. **Settings-based**: `config.profiles` section → GLM, legacy GLMT compatibility, Kimi -4. **Account-based**: `profiles.json` → isolated instances via `CLAUDE_CONFIG_DIR` - -### Settings Format (CRITICAL) - -All env values MUST be strings (not booleans/objects) to prevent PowerShell crashes. - -```json -{ - "env": { - "ANTHROPIC_BASE_URL": "https://api.example.com/anthropic", - "ANTHROPIC_AUTH_TOKEN": "your-api-key", - "ANTHROPIC_MODEL": "model-name" - } -} -``` - -### Shared Data Architecture - -Symlinked from `~/.ccs/shared/`: commands/, skills/, agents/ -Profile-specific: settings.json, sessions/, todolists/, logs/ -Windows fallback: Copies if symlinks unavailable - -## Code Standards - -### Architecture -- `lib/ccs`, `lib/ccs.ps1` - Bootstrap scripts (delegate to Node.js via npx) -- `src/*.ts` → `dist/*.js` - Main implementation (TypeScript) - -### Bash (lib/*.sh) -- bash 3.2+, `set -euo pipefail`, quote all vars `"$VAR"`, `[[ ]]` tests -- NO external dependencies - -### PowerShell (lib/*.ps1) -- PowerShell 5.1+, `$ErrorActionPreference = "Stop"` -- Native JSON only, no external dependencies - -### TypeScript (src/*.ts) -- Node.js 18+, Bun 1.0+, TypeScript 5.3, strict mode -- `child_process.spawn`, handle SIGINT/SIGTERM - -### Terminal Output -- ASCII only: [OK], [!], [X], [i] (NO emojis in CLI output) -- TTY detect before colors, respect NO_COLOR -- Box borders for errors: ╔═╗║╚╝ - -## Conventional Commits (MANDATORY) - -**ALL commits MUST follow conventional commit format. Non-compliant commits are rejected by husky.** - -### Format -``` -(): -``` - -### Types (determines version bump) - -| Type | Version Bump | Use For | -|------|--------------|---------| -| `feat:` | MINOR | New features | -| `fix:` | PATCH | Bug fixes | -| `perf:` | PATCH | Performance | -| `feat!:` | MAJOR | Breaking changes | -| `docs:`, `style:`, `refactor:`, `test:`, `chore:`, `ci:`, `build:` | None | Non-release | - -### Examples ```bash -# Good -git commit -m "feat(cliproxy): add OAuth token refresh" -git commit -m "fix(doctor): handle missing config gracefully" - -# Bad - REJECTED -git commit -m "added new feature" -git commit -m "Fixed bug" +cd /Users/kaitran/CloudPersonal/ccs/cli/ui && bun run format && bun run validate ``` -## Branching Strategy +After every push to a PR, watch CI until it finishes. If checks fail, inspect +logs, fix root cause, push again, and re-watch. -### Hierarchy -``` -main (production) ← dev (integration) ← feat/* | fix/* | docs/* - ↑ - └── hotfix/* (critical only, skips dev) -``` +## Issue Triage + +Issue triage is GitHub-only unless implementation is explicitly requested. +Always inspect live state first: -### Standard Workflow ```bash -git checkout dev && git pull origin dev -git checkout -b feat/my-feature -# ... develop with conventional commits ... -git push -u origin feat/my-feature -gh pr create --base dev --title "feat(scope): description" -# After testing in @dev: -gh pr create --base main --title "feat(release): promote dev to main" +cd /Users/kaitran/CloudPersonal/ccs/cli && gh issue view --json title,body,state,labels,assignees,comments ``` -### Hotfix Workflow (Production Emergencies Only) -```bash -git checkout main && git pull origin main -git checkout -b hotfix/critical-bug -# ... fix ... -gh pr create --base main --title "fix: critical issue" -# Then sync: git checkout dev && git merge main && git push -``` +For open issues, prefer one type label and one area label. Use routing labels +only when they affect handling: `upstream-blocked`, `needs-repro`, +`needs-split`, `docs-gap`. Do not close issues on age, intuition, or vague +titles; close only with evidence from README, docs, changelog, source, or a +canonical duplicate. -### Rules -1. **NEVER** commit directly to `main` or `dev` -2. Feature branches from `dev`, hotfixes from `main` -3. dev→main PRs MUST use `feat:` or `fix:` (not `chore:`) -4. Delete branches after merge +## Release Signals -## Automated Releases (DO NOT MANUALLY TAG) +- PR `CI` is the contributor quality gate. +- `Push CI` is the post-merge signal for `dev`. +- `Dev Release` publishes the `@dev` npm package. +- A red `Dev Release` is not automatically contributor failure; check PR `CI` + and `Push CI` first. -**Releases are FULLY AUTOMATED via semantic-release. NEVER manually bump versions or create tags.** +Use `feat:` or `fix:` for dev-to-main promotion PRs so release automation runs. -| Branch | npm Tag | When | -|--------|---------|------| -| `main` | `@latest` | Merge PR to main | -| `dev` | `@dev` | Push to dev branch | +## Design Standards -**CI handles:** version bump, CHANGELOG.md, git tag, npm publish, GitHub release. - -## Development - -### Testing (REQUIRED before PR) -```bash -bun run test # All tests -bun run test:npm # npm package tests -bun run test:native # Native install tests -bun run test:unit # Unit tests -``` - -### Local Development -```bash -bun run dev # Build + start config server (http://localhost:3000) -bun run dev:symlink # Symlink global 'ccs' → dev dist/ccs.js (fast iteration) -bun run dev:unlink # Restore original global ccs -./scripts/dev-install.sh # Build, pack, install globally (full install) -rm -rf ~/.ccs # Clean environment -``` - -**IMPORTANT:** Use `bun run dev` at CCS root for always up-to-date code. Do NOT use `ccs config` during development as it uses the globally installed version. - -## Two-Tier Pre-Push Checklist - -Optimized for iterative push-then-review workflow. Do NOT run the full gate on every push — CI is the safety net. Run the full gate once before asking for review / merge. - -### Tier 1 — Iterative push (feature branch) -Husky `pre-push` auto-runs: `typecheck + lint + format:check + test:fast` plus targeted checks based on changed files. AI does **nothing extra** at push time. - -**After push (MANDATORY):** follow the [CI-First Protocol](#ci-first-protocol-mandatory) — watch CI until green. Do not move on while CI is red. - -### Tier 2 — Before requesting review / merge -Run ONCE, not per push: -- [ ] `bun run validate:ci-parity` — branch freshness + build + full non-e2e tests + e2e -- [ ] `gh pr checks ` — all checks green -- [ ] If UI changed: `cd ui && bun run format && bun run validate` -- [ ] If touching command routing, proxy flows, workflows, or release logic: `bun run test:e2e` - -### Code / Docs / Standards (verify before merge) -- [ ] Conventional commit format (`feat:`, `fix:`, etc.) -- [ ] Respective `--help` updated (see Help Location Reference) — if CLI changed -- [ ] Tests added/updated — if behavior changed -- [ ] README.md updated — if user-facing -- [ ] CCS docs updated (owner: `~/CloudPersonal/ccs/docs/`) — if CLI/config changed -- [ ] Local `docs/` updated — if architecture changed -- [ ] CLI output ASCII only (NO emojis in terminal output), NO_COLOR respected -- [ ] YAGNI/KISS/DRY alignment verified -- [ ] No manual version bump or tags - -## Error Handling Principles - -- Validate early, fail fast with clear messages -- Show available options on mistakes -- Never leave broken state +- YAGNI, KISS, DRY. +- CLI-complete: core configuration features need CLI coverage. +- Dashboard parity: configuration features usually need dashboard coverage too. +- Execution remains CLI-first; dashboard should not replace terminal profile + launch flows. +- Error messages should help users recover, not just report failure.