Skip to content

Commit b0e5c36

Browse files
backslash-uxbackslash-ux
committed
docs: update README with Mermaid diagram and enhance agent rules
- Replace ASCII diagram with Mermaid flowchart - Add all v0.1 tools to agent rules (search_history, verify_intent, sanitize_content) - Add security enforcement behavior for security_flags - Add example workflow with new tools
1 parent cccf2e8 commit b0e5c36

2 files changed

Lines changed: 166 additions & 45 deletions

File tree

‎README.md‎

Lines changed: 78 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
<div align="center">
44

5-
**🛡️ A Git Hygiene Safety Layer for AI-First Development**
5+
**🛡️ Production-Grade Safety Layer for AI-First Development**
66

7-
_Keep your AI coding assistants honest with automatic commit hygiene checks_
7+
_Git hygiene monitoring + Security scanning + Semantic search + Full observability_
88

99
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
1010
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
@@ -16,30 +16,34 @@ _Keep your AI coding assistants honest with automatic commit hygiene checks_
1616

1717
## Why FlowCheck?
1818

19-
AI coding assistants are incredibly productive—but they can also create **massive, hard-to-review changesets** in a single session. FlowCheck acts as a safety layer that:
19+
AI coding assistants are incredibly productive—but they can also create **massive, hard-to-review changesets** and **security risks**. FlowCheck v0.1 is a production-grade safety layer that:
2020

2121
- 🔍 **Monitors Git state** in real-time during AI-assisted coding
22-
- ⚡ **Nudges agents** to make checkpoint commits before changes get too large
23-
- 📊 **Tracks flow health** (time since commit, lines changed, files modified)
24-
- 🤖 **Designed for AI agents** with enforceable rules and clear tool interfaces
22+
- 🔒 **Scans for security issues** (PII, secrets, prompt injection attacks)
23+
- 🔎 **Semantic history search** - find commits by meaning, not keywords
24+
- 📊 **Tracks flow health** (time, lines, branch age, drift from main)
25+
- 📝 **Full observability** (OpenTelemetry traces, audit logs)
26+
- 🎯 **Intent validation** (ticket-to-diff alignment)
27+
- 🤖 **Designed for AI agents** with enforceable rules
2528

26-
> Think of FlowCheck as a "smart fitness watch" for your codebase—it doesn't block, it nudges.
29+
> Think of FlowCheck as a "smart fitness watch with a biometric lock" for your codebase—it helps you code faster while actively defending against security threats.
2730
2831
## AI-First Design
2932

3033
FlowCheck is built specifically for the **agentic coding** workflow:
3134

32-
```
33-
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
34-
│ AI Agent │────▶│ FlowCheck │────▶│ Git Repo │
35-
│ (Claude, etc) │◀────│ MCP Server │◀────│ (.git) │
36-
└─────────────────┘ └─────────────────┘ └─────────────────┘
37-
│ │
38-
│ "status: warning" │
39-
│ "500+ lines pending"│
40-
▼ │
41-
Agent pauses and │
42-
suggests checkpoint ◀────────┘
35+
```mermaid
36+
flowchart LR
37+
Agent["🤖 AI Agent<br/>(Claude, Cursor, etc)"]
38+
FC["🛡️ FlowCheck<br/>MCP Server"]
39+
Git["📁 Git Repo<br/>(.git)"]
40+
41+
Agent -->|"get_flow_state()"| FC
42+
FC -->|"analyze"| Git
43+
Git -->|"metrics"| FC
44+
FC -->|"status: warning<br/>security_flags: [...]"| Agent
45+
46+
Agent -->|"⏸️ Pause & suggest<br/>checkpoint commit"| Agent
4347
```
4448

4549
### Agent Rules (Recommended)
@@ -92,12 +96,22 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
9296

9397
## MCP Tools
9498

99+
### Core Tools
100+
95101
| Tool | Purpose |
96102
| --------------------- | ---------------------------------------------------- |
97-
| `get_flow_state` | Returns current metrics (time, lines, files, status) |
98-
| `get_recommendations` | Returns actionable nudges based on thresholds |
103+
| `get_flow_state` | Returns metrics + **security_flags** (PII/injection) |
104+
| `get_recommendations` | Returns actionable nudges + **security warnings** |
99105
| `set_rules` | Dynamically adjust thresholds |
100106

107+
### v0.1 Production Features
108+
109+
| Tool | Purpose |
110+
| ------------------ | ---------------------------------------------------- |
111+
| `search_history` | **Semantic search** - find commits by meaning |
112+
| `verify_intent` | **Ticket alignment** - validate against requirements |
113+
| `sanitize_content` | **PII/secret redaction** before sharing with AI |
114+
101115
### Example: `get_flow_state`
102116

103117
```json
@@ -106,7 +120,10 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
106120
"uncommitted_lines": 520,
107121
"uncommitted_files": 8,
108122
"branch_name": "feature/api-refactor",
109-
"status": "warning"
123+
"branch_age_days": 3,
124+
"behind_main_by_commits": 12,
125+
"status": "warning",
126+
"security_flags": ["⚠️ SECRETS: Potential secrets detected in diff"]
110127
}
111128
```
112129

@@ -115,10 +132,28 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
115132
```json
116133
{
117134
"recommendations": [
135+
"🔒 SECURITY: Review security flags before committing.",
118136
"📊 You have 520 uncommitted lines. Consider splitting into focused commits.",
119-
"💡 Tip: Large changesets can be split by domain (backend vs frontend)."
137+
"🔄 You are behind main by 12 commits. Consider merging to avoid conflicts."
120138
],
121-
"status": "warning"
139+
"status": "warning",
140+
"security_flags": ["⚠️ SECRETS: Potential secrets detected in diff"]
141+
}
142+
```
143+
144+
### Example: `search_history`
145+
146+
```json
147+
{
148+
"query": "authentication changes",
149+
"results": [
150+
{
151+
"commit_hash": "a1b2c3d",
152+
"message": "Refactor OAuth token validation",
153+
"score": 0.87,
154+
"matched_terms": ["oauth", "token"]
155+
}
156+
]
122157
}
123158
```
124159

@@ -146,6 +181,26 @@ FlowCheck uses `~/.flowcheck/config.json`:
146181
| `warning` | One or more thresholds exceeded |
147182
| `danger` | Thresholds exceeded by 1.5x or more |
148183

184+
## Security Features (v0.1)
185+
186+
### Guardian Layer
187+
188+
- **PII Detection**: Emails, phone numbers, SSNs, credit cards
189+
- **Secret Scanning**: AWS keys, GitHub tokens, API keys, passwords
190+
- **Injection Filtering**: Detects prompt injection attacks in diffs
191+
192+
### Observability
193+
194+
- **OpenTelemetry Traces**: `gen_ai.*` semantic conventions
195+
- **Audit Logs**: Append-only JSON Lines format in `~/.flowcheck/audit.log`
196+
- All tool invocations are logged with trace IDs
197+
198+
### Semantic Search
199+
200+
- **TF-IDF Vectorization**: No external ML dependencies
201+
- **SQLite Storage**: Local index in `~/.flowcheck/semantic_index.db`
202+
- Find commits by meaning, not just keywords
203+
149204
## Development
150205

151206
```bash

‎rules/flowcheck-rules.md‎

Lines changed: 88 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,121 @@
11
# FlowCheck Rules for AI Agents
22

3-
> **This file instructs AI agents to enforce Git hygiene during agentic coding sessions.**
3+
> **This file instructs AI agents to enforce Git hygiene and security during agentic coding sessions.**
44
55
## FlowCheck MCP Tools
66

7-
You are given tools from the FlowCheck MCP server for maintaining Git hygiene. You `MUST` follow these rules:
7+
You are given tools from the FlowCheck MCP server. You `MUST` follow these rules:
88

9-
## 1. `get_flow_state`
9+
---
10+
11+
## 1. `get_flow_state` - Health Check
1012

1113
You `MUST` call this tool:
1214

13-
- **Before starting any new task** to assess current repository health
14-
- **Before making commits** to understand the scope of changes
15-
- **Periodically during long coding sessions** (every 15-20 tool calls)
16-
- **When resuming work** on a repository after any interruption
15+
- **Before starting any new task** to assess repository health
16+
- **Before making commits** to check for security flags
17+
- **Periodically during long sessions** (every 15-20 tool calls)
18+
- **When resuming work** after any interruption
19+
20+
**Critical**: If `security_flags` is non-empty, you `MUST NOT` proceed until issues are addressed.
1721

18-
## 2. `get_recommendations`
22+
---
23+
24+
## 2. `get_recommendations` - Actionable Guidance
1925

2026
You `MUST` call this tool:
2127

2228
- **When `get_flow_state` returns status `warning` or `danger`**
23-
- **Before proposing large refactors** to check if changes should be split
24-
- **At the end of each major task** to ensure clean commit hygiene
25-
- **When uncommitted lines exceed 300** to get guidance on splitting work
29+
- **When `security_flags` contains any items**
30+
- **Before proposing large refactors**
31+
- **When uncommitted lines exceed 300**
32+
33+
---
34+
35+
## 3. `search_history` - Semantic Context
36+
37+
You `SHOULD` call this tool:
38+
39+
- **Before implementing features** to find similar past solutions
40+
- **When debugging** to find how issues were fixed before
41+
- **Instead of `git log`** when searching by concept, not keywords
42+
43+
Example: `search_history("authentication changes", repo_path)`
44+
45+
---
46+
47+
## 4. `verify_intent` - Ticket Alignment
48+
49+
You `SHOULD` call this tool:
50+
51+
- **Before completing a task** to verify alignment with requirements
52+
- **When scope seems to be expanding** beyond the original ticket
53+
- **Before large refactors** to confirm they're in scope
54+
55+
---
2656

27-
## 3. `set_rules`
57+
## 5. `sanitize_content` - Security Redaction
58+
59+
You `MUST` call this tool:
60+
61+
- **Before including file contents in outputs** if they may contain secrets
62+
- **Before sharing code snippets** that haven't been security-scanned
63+
- **When working with config files** that may contain credentials
64+
65+
---
66+
67+
## 6. `set_rules` - Configuration
2868

2969
You `MAY` call this tool when:
3070

3171
- The user explicitly requests different thresholds
3272
- Working on a codebase with specific commit policies
3373

74+
---
75+
3476
## Enforcement Behavior
3577

36-
When FlowCheck reports `warning` or `danger` status, you `MUST`:
78+
### When status is `warning` or `danger`:
3779

38-
1. **Pause new feature work** and address the hygiene issue first
39-
2. **Suggest a checkpoint commit** if time threshold is exceeded
40-
3. **Propose splitting changes** if line count threshold is exceeded
41-
4. **Inform the user** of the flow health status and your recommendation
80+
1. **Pause new feature work** - address hygiene first
81+
2. **Suggest checkpoint commit** if time threshold exceeded
82+
3. **Propose splitting changes** if line count exceeded
83+
4. **Inform the user** of flow health status
4284

43-
## Example Integration
85+
### When `security_flags` is non-empty:
86+
87+
1. **STOP** - do not proceed with commits
88+
2. **Review** the flagged content for secrets/PII
89+
3. **Use `sanitize_content`** to redact sensitive data
90+
4. **Alert the user** about potential security issues
91+
92+
---
93+
94+
## Example Workflow
4495

4596
```
4697
Before starting work:
4798
1. Call get_flow_state(repo_path)
48-
2. If status is not "ok", call get_recommendations(repo_path)
49-
3. Address any hygiene issues before proceeding
50-
4. Begin the requested task
99+
2. Check security_flags - if non-empty, address immediately
100+
3. If status != "ok", call get_recommendations(repo_path)
101+
4. Call search_history() for relevant context
102+
5. Begin the requested task
103+
104+
Before completing work:
105+
1. Call verify_intent(ticket_id) if applicable
106+
2. Call get_flow_state() to verify clean state
107+
3. Suggest commit with descriptive message
51108
```
52109

110+
---
111+
53112
## Philosophy
54113

55-
FlowCheck is a "smart fitness watch" for coding—it nudges, never blocks. But as an AI agent, you should treat these nudges as **strong recommendations** to maintain a clean, reviewable Git history that humans can easily understand and audit.
114+
FlowCheck is a "defense-in-depth" safety layer:
115+
116+
- **Hygiene nudges** keep commits small and reviewable
117+
- **Security scanning** prevents accidental secret/PII leaks
118+
- **Semantic search** reduces duplicate work and hallucinations
119+
- **Intent validation** ensures code matches requirements
120+
121+
As an AI agent, treat FlowCheck warnings as **strong recommendations** to maintain a clean, secure, auditable Git history.

0 commit comments

Comments
 (0)