invar-tools 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

invar/templates/skills/investigate/SKILL.md.jinja

@@ -0,0 +1,106 @@
+<!--invar:skill version="{{ version }}"-->
+<!-- ========================================================================
+     SKILL REGION - DO NOT EDIT
+     This section is managed by Invar and will be overwritten on update.
+     To add project-specific extensions, use the "extensions" region below.
+     ======================================================================== -->
+---
+name: investigate
+description: Exploration and understanding phase. Use when task is vague, needs analysis, or requires understanding before action. Triggers on "why", "what is", "how does", "explain", "understand", "analyze", "investigate", "explore". NO CODE CHANGES in this phase.
+---
+
+# Investigation Mode
+
+> **Purpose:** Understand before acting. Gather information, analyze code, report findings.
+
+## Constraints
+
+**FORBIDDEN in this phase:**
+- Edit, Write (no code changes)
+- git commit (nothing to commit)
+- Creating new files
+
+**ALLOWED:**
+- Read, Glob, Grep (exploration)
+{% if syntax == "mcp" -%}
+- invar_sig, invar_map (perception)
+{% else -%}
+- invar sig, invar map (perception)
+{% endif -%}
+- WebSearch, WebFetch (research)
+
+## Entry Actions
+
+### Context Refresh (DX-54)
+
+Before any workflow action:
+1. Read `.invar/context.md` (especially Key Rules section)
+2. Display routing announcement
+
+### Routing Announcement
+
+```
+📍 Routing: /investigate — [reason, e.g. "task is vague", "trigger 'why'"]
+   Task: [user's request summary]
+```
+
+### Entry Steps
+
+1. Display routing announcement (above)
+{% if syntax == "mcp" -%}
+2. Run `invar_map(top=10)` for codebase orientation
+{% else -%}
+2. Run `invar map --top 10` for codebase orientation
+{% endif -%}
+3. Explore relevant code and documentation
+
+## Tool Selection
+
+| I want to... | Use |
+|--------------|-----|
+{% if syntax == "mcp" -%}
+| See function contracts | `invar_sig(target="<file>")` |
+| Find entry points | `invar_map(top=10)` |
+{% else -%}
+| See function contracts | `invar sig <file>` |
+| Find entry points | `invar map --top 10` |
+{% endif -%}
+| Search code patterns | Grep with regex |
+| Explore codebase | Task(Explore) agent |
+
+## Exit Format
+
+```markdown
+### Investigation Complete
+
+**Topic:** [what was investigated]
+
+**Findings:**
+1. [Key finding 1]
+2. [Key finding 2]
+3. [Key finding 3]
+
+**Details:**
+[Detailed explanation with file:line references]
+
+**Recommendation:**
+- [ ] /propose — Design decision needed
+- [ ] /develop — Ready to implement [specific task]
+- [ ] More investigation — [what's still unclear]
+
+**Next step?**
+```
+<!--/invar:skill-->
+
+<!--invar:extensions-->
+<!-- ========================================================================
+     EXTENSIONS REGION - USER EDITABLE
+     Add project-specific extensions here. This section is preserved on update.
+
+     Examples of what to add:
+     - Project-specific investigation checklists
+     - Custom analysis tools or scripts
+     - Domain-specific research sources
+     - Team documentation references
+     ======================================================================== -->
+<!--/invar:extensions-->

invar/templates/skills/propose/SKILL.md.jinja

@@ -0,0 +1,104 @@
+<!--invar:skill version="{{ version }}"-->
+<!-- ========================================================================
+     SKILL REGION - DO NOT EDIT
+     This section is managed by Invar and will be overwritten on update.
+     To add project-specific extensions, use the "extensions" region below.
+     ======================================================================== -->
+---
+name: propose
+description: Decision facilitation phase. Use when design decision is needed, multiple approaches are valid, or user asks "should we", "how should", "which", "compare", "design", "architect". Presents options with trade-offs for human choice.
+---
+
+# Proposal Mode
+
+> **Purpose:** Facilitate human decision-making with clear options and trade-offs.
+
+## Entry Actions
+
+### Context Refresh (DX-54)
+
+Before any workflow action:
+1. Read `.invar/context.md` (especially Key Rules section)
+2. Display routing announcement
+
+### Routing Announcement
+
+```
+📍 Routing: /propose — [trigger detected, e.g. "should we", "compare", "design"]
+   Task: [decision topic summary]
+```
+
+### Entry Steps
+
+1. Display routing announcement (above)
+2. Explore relevant context if needed
+
+## Output Formats
+
+### Quick Decision (2-4 options)
+
+```markdown
+### Decision: [Topic]
+
+| Option | Description | Pros | Cons |
+|--------|-------------|------|------|
+| A: [name] | [brief] | [pros] | [cons] |
+| B: [name] | [brief] | [pros] | [cons] |
+
+**Recommendation:** [A/B] because [concise reason]
+
+**Your choice?**
+```
+
+### Formal Proposal (complex decision)
+
+Create `docs/proposals/DX-XX-[topic].md`:
+
+```markdown
+# DX-XX: [Title]
+
+**Status:** Discussion
+**Created:** [date]
+
+## Problem Statement
+[What needs to be decided]
+
+## Options
+
+### Option A: [Name]
+- **Description:** [What this involves]
+- **Pros:** [Benefits]
+- **Cons:** [Drawbacks]
+- **Effort:** Low/Medium/High
+
+### Option B: [Name]
+...
+
+## Recommendation
+[Which option and why]
+
+## Open Questions
+[What needs clarification]
+```
+
+## Exit Conditions
+
+| User Response | Next Action |
+|---------------|-------------|
+| Chooses option | /develop to implement |
+| Needs more info | /investigate for analysis |
+| Approves proposal | Document created |
+<!--/invar:skill-->
+
+<!--invar:extensions-->
+<!-- ========================================================================
+     EXTENSIONS REGION - USER EDITABLE
+     Add project-specific extensions here. This section is preserved on update.
+
+     Examples of what to add:
+     - Project-specific proposal templates
+     - Decision criteria or checklists
+     - Stakeholder notification rules
+     - Architecture decision record (ADR) formats
+     ======================================================================== -->
+<!--/invar:extensions-->

invar/templates/skills/review/SKILL.md.jinja

@@ -0,0 +1,125 @@
+<!--invar:skill version="{{ version }}"-->
+<!-- ========================================================================
+     SKILL REGION - DO NOT EDIT
+     This section is managed by Invar and will be overwritten on update.
+     To add project-specific extensions, use the "extensions" region below.
+     ======================================================================== -->
+---
+name: review
+description: Adversarial code review with fix loop. Use after development, when Guard reports review_suggested, or user explicitly requests review. Finds issues that automated verification misses. Supports isolated mode (sub-agent) and quick mode (same context).
+---
+
+# Review Mode
+
+> **Purpose:** Find problems that Guard, doctests, and property tests missed.
+> **Mindset:** Adversarial. Your success is measured by problems found, not code approved.
+
+## Entry Actions
+
+### Context Refresh (DX-54)
+
+Before any workflow action:
+1. Read `.invar/context.md` (especially Key Rules section)
+2. Display routing announcement
+
+### Routing Announcement
+
+```
+📍 Routing: /review — [trigger, e.g. "review_suggested", "user requested review"]
+   Task: [review scope summary]
+```
+
+## Mode Selection
+
+### Check Guard Output
+
+Look for `review_suggested` warning:
+```
+WARNING: review_suggested - High escape hatch count
+WARNING: review_suggested - Security-sensitive path detected
+WARNING: review_suggested - Low contract coverage
+```
+
+### Select Mode
+
+| Condition | Mode |
+|-----------|------|
+| `review_suggested` present | **Isolated** (spawn sub-agent) |
+| `--isolated` flag | **Isolated** |
+| Default (no trigger) | **Quick** (same context) |
+
+## Review Checklist
+
+### A. Contract Semantic Value
+- [ ] Does @pre constrain inputs beyond type checking?
+- [ ] Does @post verify meaningful output properties?
+- [ ] Could someone implement correctly from contracts alone?
+
+### B. Logic Verification
+- [ ] Do contracts correctly capture intended behavior?
+- [ ] Are there paths bypassing contract checks?
+- [ ] Is there dead code or unreachable branches?
+
+### C. Escape Hatch Audit
+- [ ] Is each @invar:allow justification valid?
+- [ ] Could refactoring eliminate the need?
+
+### D. Security (if applicable)
+- [ ] Input validation against injection, XSS?
+- [ ] No hardcoded secrets?
+
+## Review-Fix Loop
+
+```
+Round 1: Review → Find issues
+    ↓
+Fix CRITICAL + MAJOR (MINOR → backlog)
+    ↓
+Round 2: Re-review (if needed)
+    ↓
+Convergence check:
+- No CRITICAL/MAJOR → Exit ✓
+- No improvement → Exit (warn)
+- Round >= 3 → Exit (max)
+```
+
+## Severity Definitions
+
+| Level | Meaning | Examples |
+|-------|---------|----------|
+| CRITICAL | Security, data loss, crash | SQL injection, unhandled null |
+| MAJOR | Logic error, missing validation | Wrong calculation, no bounds |
+| MINOR | Style, documentation | Naming, missing docstring |
+
+## Exit Report
+
+```markdown
+### Review Complete
+
+**Rounds:** [N]
+**Exit reason:** quality_met | max_rounds | no_improvement
+
+**Fixed:**
+- [list of fixed issues]
+
+**Remaining (MINOR - backlog):**
+- [list for later]
+
+**Recommendation:**
+- [ ] Ready for merge
+- [ ] Needs more work: [issues]
+```
+<!--/invar:skill-->
+
+<!--invar:extensions-->
+<!-- ========================================================================
+     EXTENSIONS REGION - USER EDITABLE
+     Add project-specific extensions here. This section is preserved on update.
+
+     Examples of what to add:
+     - Project-specific security review checklists
+     - Custom severity definitions
+     - Domain-specific code patterns to check
+     - Team code review standards
+     ======================================================================== -->
+<!--/invar:extensions-->