specguard-ci 0.1.0__tar.gz

specguard_ci-0.1.0/.claude/skills/clean-code/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: "clean-code"
+description: "Clean code review and refactoring skill — naming, structure, complexity, duplication, and readability for Python projects."
+argument-hint: "Optional: file path or specific concern (e.g. 'review engine.py', 'naming', 'complexity')"
+compatibility: "Python 3.12+ projects; principles apply to any language"
+metadata:
+  author: "specguard"
+  source: ".claude/skills/clean-code/SKILL.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+If a file path is provided, read and review that file. If no argument is given, review the most recently edited file or ask which file to review.
+
+## Review Checklist
+
+Work through each category. Flag issues with severity: **must fix** / **should fix** / **consider**.
+
+---
+
+### 1. Naming
+
+- [ ] Functions named as verbs: `classify_diff`, not `classifier` or `do_it`
+- [ ] Variables named for what they hold, not their type: `watched_files`, not `file_list`
+- [ ] Booleans prefixed with `is_`, `has_`, `can_`: `is_fork`, `has_qualified_approval`
+- [ ] No single-letter variables outside list comprehensions and loop indices
+- [ ] No abbreviations that require domain knowledge to decode
+- [ ] Class names are nouns: `Verdict`, `ScopeLock`, not `VerdictHandler`
+
+---
+
+### 2. Functions
+
+- [ ] Each function does one thing — if you need "and" to describe it, split it
+- [ ] Length: flag functions over ~30 lines for review
+- [ ] Parameters: flag functions with more than 4 parameters — consider a dataclass
+- [ ] No boolean flag parameters that change behaviour: split into two functions instead
+- [ ] Early returns over nested conditionals
+- [ ] No side effects in functions whose name implies a query (e.g. `get_`, `find_`, `is_`)
+
+---
+
+### 3. Comments
+
+- [ ] No comments that restate what the code does — the code says that
+- [ ] Comments only for: hidden constraints, non-obvious invariants, workarounds for external bugs
+- [ ] No commented-out code — delete it (git has history)
+- [ ] No TODO comments without a linked issue or task ID
+
+---
+
+### 4. Complexity
+
+- [ ] Cyclomatic complexity: flag any function with more than 4 branches
+- [ ] Nesting: flag more than 3 levels of indentation
+- [ ] Long chains: extract intermediate variables with meaningful names
+- [ ] Magic numbers/strings: extract to named constants at module level
+
+---
+
+### 5. Duplication
+
+- [ ] Identical logic in two places → extract a function
+- [ ] Similar logic with slight variation → consider a parameter or a shared helper
+- [ ] Copy-pasted error messages or annotation strings → extract to constants
+
+---
+
+### 6. Error handling
+
+- [ ] Catch specific exceptions, never bare `except:` or `except Exception:` without re-raise
+- [ ] Error messages name the file/field that caused the problem
+- [ ] Custom exceptions (`ConfigError`, `ClassifierError`) used at system boundaries — not `ValueError` from deep inside a module
+- [ ] No swallowed exceptions — at minimum `logger.warning` before continuing
+
+---
+
+### 7. Types (Python-specific)
+
+- [ ] All public functions have type annotations
+- [ ] `Optional[X]` written as `X | None` (Python 3.10+ style)
+- [ ] Pydantic models used for external data boundaries (API responses, config files)
+- [ ] No `Any` without a comment explaining why it cannot be narrowed
+- [ ] Return types explicit — no implicit `None` on functions that sometimes return a value
+
+---
+
+### 8. Module structure
+
+- [ ] Imports: stdlib → third-party → local, each group separated by a blank line
+- [ ] No circular imports — dependency order: `models` → `config`/`gitdiff` → `classifier`/`roles`/`approvals` → `engine` → `report`/`ci`
+- [ ] Module-level code limited to constants and `__all__` — no logic at import time
+- [ ] No `from module import *`
+
+---
+
+### 9. Tests (when reviewing test files)
+
+- [ ] Test names describe the scenario: `test_scope_change_below_threshold_warns_not_blocks`
+- [ ] One assertion concept per test (multiple `assert` lines fine if testing one thing)
+- [ ] No logic in tests (no loops, no conditionals) — if you need a loop, use `@pytest.mark.parametrize`
+- [ ] Fixtures in `conftest.py`, not repeated across test files
+- [ ] No real API calls in unit tests — `FakeAnthropicClient` only
+
+---
+
+## Output Format
+
+For each issue found:
+
+```
+[SEVERITY] Category — Description
+File: path/to/file.py, line N
+Issue: what is wrong
+Fix:   what to change it to (or a concrete suggestion)
+```
+
+After listing all issues, provide a **Refactoring Plan** — ordered by impact, highest first — with estimated effort (S/M/L) for each item.
+
+If no issues are found in a category, note it as ✅ and move on.
+
+---
+
+## Rules
+
+- Do not refactor beyond what was requested — flag issues, do not silently rewrite
+- Do not add abstractions that are not needed by existing code
+- Do not add error handling for scenarios that cannot occur
+- When suggesting a rename, show the before and after in context — not just the new name
+- Constitution IV applies: clean code must not introduce friction on the additive path

specguard_ci-0.1.0/.claude/skills/git/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: "git"
+description: "Git workflow skill — branch management, commits, PRs, rebasing, and conflict resolution following project conventions."
+argument-hint: "Optional: specific git operation (e.g. 'new branch', 'pr', 'cleanup', 'undo')"
+compatibility: "Requires a git repository"
+metadata:
+  author: "specguard"
+  source: ".claude/skills/git/SKILL.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+Consider the user input before selecting which operation to perform.
+
+## Operations
+
+### Branch
+
+**Create a feature branch** (when user says "new branch", "start feature", or similar):
+- Name format: `NNN-short-description` (e.g. `002-classifier-core`)
+- Always branch from the latest `main`: `git checkout main && git pull && git checkout -b <name>`
+- Report the branch name created
+
+**Switch branch**: `git checkout <branch>` — list available branches first if name is ambiguous
+
+**Delete merged branch**: confirm the branch is merged into main before deleting
+
+---
+
+### Commit
+
+Follow this sequence every time:
+1. `git status` — review what changed
+2. `git diff` — understand the changes
+3. Stage specific files by name — never `git add .` or `git add -A`
+4. Write the commit message using the Conventional Commits format:
+
+   ```
+   <type>(<scope>): <short summary>
+
+   <optional body — the WHY, not the what>
+
+   Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+   ```
+
+   Types: `feat` `fix` `docs` `refactor` `test` `chore` `perf`
+
+5. Always pass the message via heredoc:
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   feat(classifier): add prompt caching with ephemeral cache_control
+   EOF
+   )"
+   ```
+
+**Never**:
+- Skip hooks (`--no-verify`)
+- Amend published commits
+- Commit `.env`, credentials, or binary blobs not already tracked
+
+---
+
+### Pull Request
+
+1. `git log main..HEAD --oneline` — summarize what's on the branch
+2. `git diff main...HEAD` — review all changes
+3. Push branch: `git push -u origin <branch>`
+4. Create PR via `gh pr create`:
+
+   ```bash
+   gh pr create --title "<type>: <summary under 70 chars>" --body "$(cat <<'EOF'
+   ## Summary
+   - <bullet 1>
+   - <bullet 2>
+
+   ## Test plan
+   - [ ] <validation step>
+
+   🤖 Generated with [Claude Code](https://claude.ai/claude-code)
+   EOF
+   )"
+   ```
+
+5. Return the PR URL
+
+---
+
+### Rebase & Sync
+
+**Sync feature branch with main**:
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+Resolve conflicts file by file — never discard changes without showing the user what would be lost.
+
+**Interactive rebase** — not supported (requires interactive terminal). Use fixup commits and `git rebase origin/main` instead.
+
+---
+
+### Undo
+
+| Situation | Safe command |
+|---|---|
+| Unstage a file | `git restore --staged <file>` |
+| Discard uncommitted changes to a file | `git restore <file>` (destructive — confirm first) |
+| Undo last commit, keep changes staged | `git reset --soft HEAD~1` |
+| Find a lost commit | `git reflog` |
+
+**Never** `git reset --hard` or `git push --force` on `main` without explicit user instruction.
+
+---
+
+### Cleanup
+
+- Delete local branches already merged to main: `git branch --merged main | grep -v main | xargs git branch -d`
+- Show branches: `git branch -vv`
+- Show log: `git log --oneline --graph --decorate -20`
+
+---
+
+## Rules
+
+- Confirm before any destructive operation (reset --hard, force push, branch delete)
+- Prefer creating new commits over amending
+- Never push directly to `main` unless the user explicitly says so
+- Always verify the remote URL before pushing to a new remote

specguard_ci-0.1.0/.claude/skills/speckit-agent-context-update/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: speckit-agent-context-update
+description: Refresh the managed Spec Kit section in the coding agent context file
+compatibility: Requires spec-kit project structure with .specify/ directory
+metadata:
+  author: github-spec-kit
+  source: agent-context:commands/speckit.agent-context.update.md
+---
+
+# Update Coding Agent Context
+
+Refresh the managed Spec Kit section inside the active coding agent's context/instruction file (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`).
+
+## Behavior
+
+The script reads the agent-context extension config at
+`.specify/extensions/agent-context/agent-context-config.yml` to discover:
+
+- `context_file` — the path of the coding agent context file to manage.
+- `context_markers.start` / `.end` — the delimiters surrounding the managed section. Defaults to `<!-- SPECKIT START -->` and `<!-- SPECKIT END -->` when the field is missing.
+
+It then creates, replaces, or appends the managed block so that the section points at the most recent plan path when one can be discovered (`specs/<feature>/plan.md`).
+
+If `context_file` is empty or the file cannot be located, the command reports nothing to do and exits successfully.
+
+## Execution
+
+- **Bash**: `.specify/extensions/agent-context/scripts/bash/update-agent-context.sh [plan_path]`
+- **PowerShell**: `.specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1 [plan_path]`
+
+When `plan_path` is omitted, the script auto-detects the most recently modified `specs/*/plan.md`.

specguard_ci-0.1.0/.claude/skills/speckit-analyze/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: "speckit-analyze"
+description: "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
+argument-hint: "Optional focus areas for analysis"
+compatibility: "Requires spec-kit project structure with .specify/ directory"
+metadata:
+  author: "github-spec-kit"
+  source: "templates/commands/analyze.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before analysis)**:
+- Check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` → `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Goal.
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit-tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit-analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit-implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit-specify with refinement", "Run /speckit-plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+### 9. Check for extension hooks
+
+After reporting, check if `.specify/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `speckit.git.commit` → `/speckit-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS