Skip to content

Commit 0a9f904

Browse files
stranmastranma
authored
Merge pull request #24 from stranma/feat/adopt-starter-kit-features
feat: Add CoVe commands, template sync, and Python SOLID checklist
2 parents 1c49677 + 5615fd1 commit 0a9f904

10 files changed

Lines changed: 356 additions & 9 deletions

File tree

‎.claude/agents/refactoring-specialist.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,15 @@ You are a Refactoring Specialist for Python projects. You perform read-only anal
2121
| **Interface Segregation** | Large interfaces forcing implementations of unused methods, "god" base classes |
2222
| **Dependency Inversion** | High-level modules importing low-level modules directly, no abstraction boundaries |
2323

24+
### Python-Specific SOLID Checks
25+
26+
- **Mutable default arguments** (`def f(x=[])`) -- shared state across calls, use `None` + assignment
27+
- **ABC/Protocol misuse** -- prefer `typing.Protocol` for structural subtyping over `abc.ABC` when callers only need a subset of methods (Interface Segregation)
28+
- **Missing dependency injection** -- classes that instantiate their own dependencies internally instead of accepting them via `__init__` (Dependency Inversion)
29+
- **God classes** -- classes with 10+ public methods or mixed concerns (data access + business logic + formatting)
30+
- **`@property` overuse** -- properties hiding expensive computation or side effects; prefer explicit methods when the operation is not trivially cheap
31+
- **Circular imports** -- modules importing each other signals entangled responsibilities (Single Responsibility)
32+
2433
## Code Smells to Detect
2534

2635
### Size Smells

‎.claude/commands/cove-isolated.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
allowed-tools: Read, Glob, Grep, Bash, Agent
3+
description: Isolated Chain-of-Verification (CoVe) -- verification step runs in a separate agent to prevent confirmation bias.
4+
---
5+
6+
<!-- Inspired by serpro69/claude-starter-kit; based on Meta's CoVe paper (arxiv.org/abs/2309.11495) -->
7+
8+
# Isolated Chain-of-Verification (CoVe)
9+
10+
Apply the 4-step CoVe process with **isolated verification** -- Step 3 runs in a separate agent that cannot see the baseline response, preventing confirmation bias.
11+
12+
## Step 1: Generate Baseline Response
13+
14+
Answer the user's question fully, as you normally would. Write out your complete response under a heading:
15+
16+
```markdown
17+
## Baseline Response
18+
[your full answer here]
19+
```
20+
21+
## Step 2: Plan Verification Questions
22+
23+
Review your baseline response and generate a numbered list of fact-check questions. Focus on claims that could be wrong -- file paths, function signatures, API behavior, version numbers, configuration syntax, behavioral assertions.
24+
25+
```markdown
26+
## Verification Questions
27+
1. [Is the file path X correct?]
28+
2. [Does function Y actually accept parameter Z?]
29+
3. [Is it true that library A supports feature B?]
30+
...
31+
```
32+
33+
Generate 3-8 questions depending on response complexity.
34+
35+
## Step 3: Isolated Verification (Agent)
36+
37+
Launch a general-purpose Agent to answer the verification questions **independently**. The agent must NOT see your baseline response -- only the verification questions. This prevents confirmation bias.
38+
39+
Provide the agent with:
40+
- The numbered list of verification questions from Step 2
41+
- Instructions to use Read, Grep, Glob, and Bash to find evidence
42+
- Instructions to answer each question with CONFIRMED or INCORRECT plus evidence
43+
44+
Example agent prompt:
45+
```
46+
Answer each of these fact-check questions by investigating the codebase. For each question, respond with CONFIRMED or INCORRECT and cite your evidence.
47+
48+
Questions:
49+
1. [question 1]
50+
2. [question 2]
51+
...
52+
```
53+
54+
## Step 4: Generate Final Verified Response
55+
56+
Review the agent's verification results and revise your baseline response, incorporating all corrections. If no errors were found, state that the baseline was verified and present it as final.
57+
58+
```markdown
59+
## Verified Response
60+
[corrected answer, incorporating all verification results]
61+
```
62+
63+
If any corrections were made, add a brief summary:
64+
65+
```markdown
66+
## Corrections Made
67+
- [what changed and why]
68+
```

‎.claude/commands/cove.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
allowed-tools: Read, Glob, Grep, Bash
3+
description: Chain-of-Verification (CoVe) prompting for high-stakes accuracy. Generates a response, self-verifies with fact-check questions, then revises.
4+
---
5+
6+
<!-- Inspired by serpro69/claude-starter-kit; based on Meta's CoVe paper (arxiv.org/abs/2309.11495) -->
7+
8+
# Chain-of-Verification (CoVe)
9+
10+
Apply the 4-step CoVe process to reduce hallucinations and factual errors in your response to the user's question.
11+
12+
## Step 1: Generate Baseline Response
13+
14+
Answer the user's question fully, as you normally would. Write out your complete response under a heading:
15+
16+
```markdown
17+
## Baseline Response
18+
[your full answer here]
19+
```
20+
21+
## Step 2: Plan Verification Questions
22+
23+
Review your baseline response and generate a numbered list of fact-check questions. Focus on claims that could be wrong -- file paths, function signatures, API behavior, version numbers, configuration syntax, behavioral assertions.
24+
25+
```markdown
26+
## Verification Questions
27+
1. [Is the file path X correct?]
28+
2. [Does function Y actually accept parameter Z?]
29+
3. [Is it true that library A supports feature B?]
30+
...
31+
```
32+
33+
Generate 3-8 questions depending on response complexity.
34+
35+
## Step 3: Answer Verifications
36+
37+
Answer each verification question independently. Use tools (Read, Grep, Glob, Bash) to check facts against the actual codebase, documentation, or runtime behavior. Do not rely on your baseline response -- verify from source.
38+
39+
```markdown
40+
## Verification Results
41+
1. [CONFIRMED / INCORRECT] -- [evidence]
42+
2. [CONFIRMED / INCORRECT] -- [evidence]
43+
...
44+
```
45+
46+
## Step 4: Generate Final Verified Response
47+
48+
Revise your baseline response, incorporating all corrections from Step 3. If no errors were found, state that the baseline was verified and present it as final.
49+
50+
```markdown
51+
## Verified Response
52+
[corrected answer, incorporating all verification results]
53+
```
54+
55+
If any corrections were made, add a brief summary:
56+
57+
```markdown
58+
## Corrections Made
59+
- [what changed and why]
60+
```

‎.github/workflows/template-sync.yml‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Inspired by serpro69/claude-starter-kit template-sync approach
2+
name: Template Sync
3+
4+
on:
5+
workflow_dispatch:
6+
inputs:
7+
dry_run:
8+
description: "Show changes without creating a PR"
9+
type: boolean
10+
default: false
11+
template_repo:
12+
description: "Upstream template repository (owner/repo)"
13+
type: string
14+
default: "stranma/claude-code-python-template"
15+
template_branch:
16+
description: "Upstream template branch"
17+
type: string
18+
default: "master"
19+
schedule:
20+
- cron: "0 9 * * 1" # Weekly on Monday at 09:00 UTC
21+
22+
permissions:
23+
contents: write
24+
pull-requests: write
25+
26+
jobs:
27+
sync:
28+
name: Sync from upstream template
29+
runs-on: ubuntu-latest
30+
steps:
31+
- name: Checkout
32+
uses: actions/checkout@v4
33+
with:
34+
fetch-depth: 0
35+
36+
- name: Configure git
37+
run: |
38+
git config user.name "github-actions[bot]"
39+
git config user.email "github-actions[bot]@users.noreply.github.com"
40+
41+
- name: Determine template repo
42+
id: config
43+
run: |
44+
REPO="${{ inputs.template_repo || 'stranma/claude-code-python-template' }}"
45+
BRANCH="${{ inputs.template_branch || 'master' }}"
46+
echo "repo=${REPO}" >> "$GITHUB_OUTPUT"
47+
echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
48+
echo "Syncing from ${REPO}@${BRANCH}"
49+
50+
- name: Add upstream remote and fetch
51+
run: |
52+
git remote add upstream "https://github.com/${{ steps.config.outputs.repo }}.git" || true
53+
git fetch upstream "${{ steps.config.outputs.branch }}"
54+
55+
- name: Compute template diff
56+
id: diff
57+
env:
58+
UPSTREAM_BRANCH: ${{ steps.config.outputs.branch }}
59+
run: |
60+
# Paths managed by the template (synced from upstream)
61+
# Defined once here; reused in the apply step via GITHUB_OUTPUT
62+
TEMPLATE_PATHS=".claude/agents/ .claude/commands/ .claude/hooks/ .claude/rules/ .claude/skills/ .devcontainer/ .github/workflows/ docs/DEVELOPMENT_PROCESS.md"
63+
echo "template_paths=${TEMPLATE_PATHS}" >> "$GITHUB_OUTPUT"
64+
65+
# Get changed files between local and upstream
66+
CHANGED=$(git diff --name-only HEAD "upstream/${UPSTREAM_BRANCH}" -- ${TEMPLATE_PATHS} 2>/dev/null || true)
67+
68+
if [ -z "$CHANGED" ]; then
69+
echo "No template changes found"
70+
echo "has_changes=false" >> "$GITHUB_OUTPUT"
71+
else
72+
echo "Template changes detected:"
73+
echo "$CHANGED"
74+
echo "has_changes=true" >> "$GITHUB_OUTPUT"
75+
# Store diff summary for PR body
76+
DIFF_STAT=$(git diff --stat HEAD "upstream/${UPSTREAM_BRANCH}" -- ${TEMPLATE_PATHS} 2>/dev/null || true)
77+
{
78+
echo "diff_stat<<EOF"
79+
echo "$DIFF_STAT"
80+
echo "EOF"
81+
} >> "$GITHUB_OUTPUT"
82+
fi
83+
84+
- name: Show diff (dry run)
85+
if: steps.diff.outputs.has_changes == 'true' && (inputs.dry_run == true || inputs.dry_run == 'true')
86+
run: |
87+
echo "=== DRY RUN: Changes that would be synced ==="
88+
echo "${{ steps.diff.outputs.diff_stat }}"
89+
90+
- name: Apply template changes
91+
id: apply
92+
if: steps.diff.outputs.has_changes == 'true' && inputs.dry_run != true && inputs.dry_run != 'true'
93+
env:
94+
UPSTREAM_BRANCH: ${{ steps.config.outputs.branch }}
95+
TEMPLATE_PATHS: ${{ steps.diff.outputs.template_paths }}
96+
run: |
97+
SYNC_BRANCH="template-sync/$(date +%Y%m%d)"
98+
99+
# Check if branch already exists
100+
if git rev-parse --verify "refs/heads/${SYNC_BRANCH}" > /dev/null 2>&1; then
101+
echo "Sync branch ${SYNC_BRANCH} already exists, updating"
102+
git checkout "${SYNC_BRANCH}"
103+
else
104+
git checkout -b "${SYNC_BRANCH}"
105+
fi
106+
107+
# Checkout template-managed files from upstream
108+
for path in ${TEMPLATE_PATHS}; do
109+
git checkout "upstream/${UPSTREAM_BRANCH}" -- "${path}" 2>/dev/null || true
110+
done
111+
112+
# Stage and commit
113+
git add -A
114+
if git diff --cached --quiet; then
115+
echo "No changes to commit after checkout"
116+
echo "changes_applied=false" >> "$GITHUB_OUTPUT"
117+
exit 0
118+
fi
119+
120+
echo "changes_applied=true" >> "$GITHUB_OUTPUT"
121+
122+
git commit -m "chore: sync template from upstream
123+
124+
Source: ${{ steps.config.outputs.repo }}@${{ steps.config.outputs.branch }}"
125+
126+
git push -u origin "${SYNC_BRANCH}"
127+
128+
echo "sync_branch=${SYNC_BRANCH}" >> "$GITHUB_ENV"
129+
130+
- name: Create pull request
131+
if: steps.apply.outputs.changes_applied == 'true' && inputs.dry_run != true && inputs.dry_run != 'true'
132+
env:
133+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
134+
run: |
135+
# Check for existing PR from this branch
136+
EXISTING_PR=$(gh pr list --head "${{ env.sync_branch }}" --json number --jq '.[0].number' 2>/dev/null || true)
137+
138+
if [ -n "$EXISTING_PR" ]; then
139+
echo "PR #${EXISTING_PR} already exists for this sync branch"
140+
exit 0
141+
fi
142+
143+
gh pr create \
144+
--title "chore: sync upstream template changes" \
145+
--body "$(cat <<'EOF'
146+
## Template Sync
147+
148+
Automated sync of template-managed files from upstream.
149+
150+
**Source:** ${{ steps.config.outputs.repo }}@${{ steps.config.outputs.branch }}
151+
152+
### Changed files
153+
```
154+
${{ steps.diff.outputs.diff_stat }}
155+
```
156+
157+
### What to review
158+
- Check if any synced files conflict with project-specific customizations
159+
- Template-managed paths: `.claude/`, `.devcontainer/`, `.github/workflows/`, `docs/DEVELOPMENT_PROCESS.md`
160+
- Project-specific files (`apps/`, `libs/`, `tests/`, `pyproject.toml`, `README.md`) are NOT touched
161+
162+
### How to resolve conflicts
163+
If a synced file conflicts with local changes, edit the file on this branch to keep your customizations, then merge.
164+
EOF
165+
)"
166+
167+
- name: Summary
168+
if: steps.diff.outputs.has_changes == 'false'
169+
run: echo "Already up to date with upstream template. No sync needed."

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,8 @@ actual scope at completion based on workspace signals.
196196
- `/design` -- crystallize brainstorming into a structured plan
197197
- `/done` -- validate, ship, and document in one command
198198
- `/catchup` -- restore context after session break or `/clear`
199+
- `/cove` -- Chain-of-Verification for high-stakes accuracy (4-step self-verification)
200+
- `/cove-isolated` -- CoVe with isolated verification agent (prevents confirmation bias)
199201
- `/security-audit` -- 6-phase security posture scan with A-F grading
200202
- `/edit-permissions` -- manage Claude Code permission rules
201203

@@ -233,7 +235,7 @@ my-project/
233235
│ ├── settings.json
234236
│ ├── agents/ # 12 agents
235237
│ ├── skills/ # /sync, /design, /done, /edit-permissions
236-
│ ├── commands/ # /catchup, /security-audit
238+
│ ├── commands/ # /catchup, /cove, /cove-isolated, /security-audit
237239
│ ├── hooks/ # 5 hook scripts
238240
│ └── rules/ # 4 review rules
239241
├── .devcontainer/ # VS Code devcontainer
@@ -306,6 +308,8 @@ Monorepo structure inspired by [carderne/postmodern-mono](https://github.com/car
306308
- Claude Code methodology layer (CLAUDE.md, agents, skills, hooks)
307309
- Setup script for template initialization
308310

311+
Chain-of-Verification commands and template sync workflow inspired by [serpro69/claude-starter-kit](https://github.com/serpro69/claude-starter-kit), a language-agnostic Claude Code starter template with MCP server integrations. Python SOLID checklist items in the refactoring-specialist agent also draw from their structured code review approach.
312+
309313
## License
310314

311315
MIT

‎docs/CHANGELOG.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11+
- Chain-of-Verification (CoVe) commands (`/cove`, `/cove-isolated`) for high-stakes accuracy -- 4-step self-verification process based on Meta's CoVe paper, with an isolated variant that runs verification in a separate agent to prevent confirmation bias
12+
- Template sync workflow (`.github/workflows/template-sync.yml`) for downstream projects to auto-sync upstream template improvements -- runs weekly or on manual trigger, creates PRs with changed template-managed files while preserving project-specific code
13+
- Python-specific SOLID checklist in `refactoring-specialist` agent -- checks for mutable default arguments, ABC/Protocol misuse, missing dependency injection, god classes, `@property` overuse, and circular imports
1114
- Template integration CI pipeline (`template-integration.yml`) tests `setup_project.py` across 5 configurations (mono-default, mono-renamed, mono-extra-pkgs, single-package, mono-postgres) -- verifies each produces a valid project that installs, lints, type-checks, and passes tests
1215
- Reusable `scripts/test_template_integration.sh` for local template validation with the same 9-step verification as CI
1316
- Workflow skill `/sync` checks workspace readiness before starting work (git fetch, status, branch info, warnings)
1417
- Workflow skill `/design` crystallizes brainstorming into structured plans with conflict detection against DECISIONS.md
1518
- Workflow skill `/done` auto-detects scope (Q/S/P) and runs the full validate-ship-document pipeline, including the former `/ship` checklist
1619
- Three graduated permission tiers (Assisted, Autonomous, Full Trust) for devcontainer environments -- container isolation (firewall, non-root, hooks) enables safely expanding Claude Code permissions, reducing unnecessary prompts from dozens per session to zero in Tier 2/3 while blocking tool installation, package publishing, and container escape vectors via curated deny lists and a policy-enforcement hook
1720
- 5 hook scripts in `.claude/hooks/` run automatically during Claude Code sessions -- 3 security hooks block destructive commands, secret leaks, and invisible Unicode attacks in real time; 2 productivity hooks auto-format Python files and auto-run associated tests after every edit
18-
- 2 slash commands (`/catchup`, `/security-audit`) provide one-command context restoration after `/clear` and a 6-phase security posture scan with A-F grading
21+
- 4 slash commands (`/catchup`, `/cove`, `/cove-isolated`, `/security-audit`) provide context restoration, chain-of-verification for accuracy, and a 6-phase security posture scan with A-F grading
1922
- 3 new specialized agents: `security-auditor` (OWASP-based vulnerability analysis, read-only), `refactoring-specialist` (SOLID/code smell detection, read-only), `output-evaluator` (LLM-as-Judge quality scoring for automated pipelines)
2023
- 4 review rules in `.claude/rules/` auto-loaded as project context -- cover architecture, code quality, performance, and test quality concerns that linters cannot catch
2124
- AI-powered PR review via GitHub Actions (`claude-code-review.yml`) using `anthropics/claude-code-action@v1` -- automatically reviews PRs with read-only tools on open/sync/ready_for_review

‎docs/DEVELOPMENT_PROCESS.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,11 +161,13 @@ All hooks require `jq` for JSON parsing and degrade gracefully if jq is missing.
161161

162162
## Commands
163163

164-
2 slash commands in `.claude/commands/`:
164+
4 slash commands in `.claude/commands/`:
165165

166166
| Command | Purpose |
167167
|---------|---------|
168168
| `/catchup` | Context restoration after `/clear`. Reads IMPLEMENTATION_PLAN.md, CHANGELOG.md, git history; recommends next steps. |
169+
| `/cove` | Chain-of-Verification (CoVe) for high-stakes accuracy. 4-step process: generate baseline, plan verifications, verify from source, produce corrected response. |
170+
| `/cove-isolated` | Isolated CoVe variant. Verification step runs in a separate agent that cannot see the baseline response, preventing confirmation bias. |
169171
| `/security-audit` | 6-phase Python security scan (deps, secrets, code patterns, input validation, config, scoring). Outputs A-F grade. |
170172

171173
---

0 commit comments

Comments
 (0)