styrene-cleave 0.1.0__tar.gz

styrene_cleave-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# Cleave workspaces (generated during execution)
+.cleave/
+
+# OS
+.DS_Store
+Thumbs.db

styrene_cleave-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 styrene-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

styrene_cleave-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: styrene-cleave
+Version: 0.1.0
+Summary: Recursive task decomposition for Claude Code - domain-aware splitting and reunification
+Project-URL: Repository, https://github.com/styrene-lab/cleave
+Author: styrene-lab
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,claude,cleave,cli,task-decomposition
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cleave
+
+Recursive task decomposition for Claude Code. Split complex directives along domain boundaries, execute in parallel, reunify with conflict detection.
+
+## Etymology
+
+"Cleave" holds contradictory meanings: to split apart AND to hold fast together. This duality captures the tool's essence—we cleave tasks into independent pieces, then cleave the results back into a unified whole.
+
+## Installation
+
+Both the CLI tool and Claude Code skill are required for full functionality.
+
+```bash
+# 1. Clone the repo
+git clone git@github.com:styrene-lab/cleave.git ~/projects/cleave
+
+# 2. Install the CLI (editable mode for easy updates)
+pip install -e ~/projects/cleave
+
+# 3. Symlink the skill definition to Claude Code's discovery path
+ln -sf ~/projects/cleave/src/cleave/skill ~/.claude/skills/cleave
+
+# 4. Verify
+cleave --help
+```
+
+To update later:
+```bash
+cd ~/projects/cleave && git pull
+# CLI updates automatically (editable install)
+# Skill symlink remains valid
+```
+
+## Usage
+
+### Within Claude Code
+
+Invoke via `/cleave` in any Claude Code session:
+
+```
+/cleave
+
+Implement user authentication with JWT tokens, ensuring backwards
+compatibility with existing session-based auth. Include migration
+path and tests.
+```
+
+Claude will:
+1. Assess complexity
+2. Split into 2-3 child tasks if needed
+3. Execute children (parallel or sequential)
+4. Reunify results with conflict detection
+
+### CLI Commands
+
+```bash
+# Assess complexity of a directive
+cleave assess --directive "Add user auth with JWT"
+
+# Match against known patterns
+cleave match --directive "Add Stripe payments"
+
+# Initialize workspace for manual execution
+cleave init --directive "Add auth" --children '["Backend", "Frontend"]'
+
+# Detect conflicts between task results
+cleave conflicts --results ".cleave/0-task.md,.cleave/1-task.md"
+
+# Reunify completed tasks
+cleave reunify --workspace .cleave
+```
+
+## Concepts
+
+### Complexity Assessment
+
+**Formula**: `complexity = (1 + systems) × (1 + 0.5 × modifiers)`
+
+- **Systems**: Distinct architectural boundaries (UI, API, DB, external services)
+- **Modifiers**: State coordination, error handling, concurrency, security, etc.
+
+If `complexity > threshold`, the directive gets cleaved.
+
+### Splitting Strategy
+
+- **Binary (2)**: Clean frontend/backend or data/logic seams
+- **Ternary (3)**: Multi-layer stacks (UI/API/DB)
+- **Never 4+**: Coordination overhead exceeds benefits
+
+### Workspace Structure
+
+```
+.cleave/
+├── manifest.yaml      # Intent, ancestry, children, assessment
+├── siblings.yaml      # Sibling coordination, file claims
+├── 0-task.md          # Child 0 task file
+├── 1-task.md          # Child 1 task file
+├── metrics.yaml       # Telemetry
+├── merge.md           # Reunification report
+└── review.md          # Adversarial review
+```
+
+### Conflict Detection
+
+Four conflict types detected during reunification:
+
+1. **File Overlap** - Multiple children modified same file
+2. **Decision Contradiction** - Incompatible choices (Redis vs Memcached)
+3. **Interface Mismatch** - Different signatures for same function
+4. **Assumption Violation** - Child assumption contradicts sibling decision
+
+## Configuration
+
+### Modes
+
+- **Lean** (default): Terse output, fast-path assessment
+- **Robust**: Verbose reasoning, sequential thinking for all assessments
+
+### Flags
+
+- `--no-tdd`: Skip TDD workflow instructions in task files
+- `--no-review`: Skip adversarial review during reunification
+- `--infer-permissions`: Detect required bash permissions upfront
+
+## Requirements
+
+- Python 3.11+
+- Claude Code CLI (for skill usage)
+- Sequential Thinking MCP server (recommended for complex assessments)
+
+## License
+
+MIT

styrene_cleave-0.1.0/README.md

@@ -0,0 +1,133 @@
+# Cleave
+
+Recursive task decomposition for Claude Code. Split complex directives along domain boundaries, execute in parallel, reunify with conflict detection.
+
+## Etymology
+
+"Cleave" holds contradictory meanings: to split apart AND to hold fast together. This duality captures the tool's essence—we cleave tasks into independent pieces, then cleave the results back into a unified whole.
+
+## Installation
+
+Both the CLI tool and Claude Code skill are required for full functionality.
+
+```bash
+# 1. Clone the repo
+git clone git@github.com:styrene-lab/cleave.git ~/projects/cleave
+
+# 2. Install the CLI (editable mode for easy updates)
+pip install -e ~/projects/cleave
+
+# 3. Symlink the skill definition to Claude Code's discovery path
+ln -sf ~/projects/cleave/src/cleave/skill ~/.claude/skills/cleave
+
+# 4. Verify
+cleave --help
+```
+
+To update later:
+```bash
+cd ~/projects/cleave && git pull
+# CLI updates automatically (editable install)
+# Skill symlink remains valid
+```
+
+## Usage
+
+### Within Claude Code
+
+Invoke via `/cleave` in any Claude Code session:
+
+```
+/cleave
+
+Implement user authentication with JWT tokens, ensuring backwards
+compatibility with existing session-based auth. Include migration
+path and tests.
+```
+
+Claude will:
+1. Assess complexity
+2. Split into 2-3 child tasks if needed
+3. Execute children (parallel or sequential)
+4. Reunify results with conflict detection
+
+### CLI Commands
+
+```bash
+# Assess complexity of a directive
+cleave assess --directive "Add user auth with JWT"
+
+# Match against known patterns
+cleave match --directive "Add Stripe payments"
+
+# Initialize workspace for manual execution
+cleave init --directive "Add auth" --children '["Backend", "Frontend"]'
+
+# Detect conflicts between task results
+cleave conflicts --results ".cleave/0-task.md,.cleave/1-task.md"
+
+# Reunify completed tasks
+cleave reunify --workspace .cleave
+```
+
+## Concepts
+
+### Complexity Assessment
+
+**Formula**: `complexity = (1 + systems) × (1 + 0.5 × modifiers)`
+
+- **Systems**: Distinct architectural boundaries (UI, API, DB, external services)
+- **Modifiers**: State coordination, error handling, concurrency, security, etc.
+
+If `complexity > threshold`, the directive gets cleaved.
+
+### Splitting Strategy
+
+- **Binary (2)**: Clean frontend/backend or data/logic seams
+- **Ternary (3)**: Multi-layer stacks (UI/API/DB)
+- **Never 4+**: Coordination overhead exceeds benefits
+
+### Workspace Structure
+
+```
+.cleave/
+├── manifest.yaml      # Intent, ancestry, children, assessment
+├── siblings.yaml      # Sibling coordination, file claims
+├── 0-task.md          # Child 0 task file
+├── 1-task.md          # Child 1 task file
+├── metrics.yaml       # Telemetry
+├── merge.md           # Reunification report
+└── review.md          # Adversarial review
+```
+
+### Conflict Detection
+
+Four conflict types detected during reunification:
+
+1. **File Overlap** - Multiple children modified same file
+2. **Decision Contradiction** - Incompatible choices (Redis vs Memcached)
+3. **Interface Mismatch** - Different signatures for same function
+4. **Assumption Violation** - Child assumption contradicts sibling decision
+
+## Configuration
+
+### Modes
+
+- **Lean** (default): Terse output, fast-path assessment
+- **Robust**: Verbose reasoning, sequential thinking for all assessments
+
+### Flags
+
+- `--no-tdd`: Skip TDD workflow instructions in task files
+- `--no-review`: Skip adversarial review during reunification
+- `--infer-permissions`: Detect required bash permissions upfront
+
+## Requirements
+
+- Python 3.11+
+- Claude Code CLI (for skill usage)
+- Sequential Thinking MCP server (recommended for complex assessments)
+
+## License
+
+MIT

styrene_cleave-0.1.0/examples/api-refactor.calf

@@ -0,0 +1,4 @@
+Refactor the API layer to use async handlers throughout. Currently
+mixing sync and async patterns causing connection pool exhaustion
+under load. Maintain backwards compatibility with existing clients.
+Add integration tests for the new async paths.

styrene_cleave-0.1.0/examples/auth-migration.calf

@@ -0,0 +1,4 @@
+Implement JWT-based authentication alongside existing session auth.
+Sessions should remain valid during 30-day migration window.
+Add /auth/token endpoint for JWT issuance. Update middleware to
+accept both auth methods. Include migration guide for API consumers.

styrene_cleave-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "styrene-cleave"
+version = "0.1.0"
+description = "Recursive task decomposition for Claude Code - domain-aware splitting and reunification"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "styrene-lab" }
+]
+keywords = ["claude", "agent", "task-decomposition", "cli", "cleave"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+    "mypy>=1.8",
+    "types-PyYAML",
+]
+
+[project.scripts]
+cleave = "cleave.cli:main"
+
+[project.urls]
+Repository = "https://github.com/styrene-lab/cleave"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cleave"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

styrene_cleave-0.1.0/src/cleave/__init__.py

@@ -0,0 +1,77 @@
+"""Cleave - Task decomposition library for complex directive management.
+
+This library provides the core algorithms for the Cleave skill:
+- Complexity assessment and pattern matching
+- Workspace generation and task file management
+- Conflict detection during reunification
+- Permission inference for fire-and-forget execution
+
+Usage:
+    from cleave import assess_directive, init_workspace, reunify_workspace
+    from cleave.core.assessment import match_pattern, calculate_complexity
+    from cleave.core.conflicts import detect_conflicts
+"""
+
+from cleave.core.assessment import (
+    AssessmentResult,
+    PatternMatch,
+    assess_directive,
+    calculate_complexity,
+    detect_modifiers,
+    effective_complexity,
+    match_pattern,
+)
+from cleave.core.conflicts import Conflict, detect_conflicts
+from cleave.core.permissions import (
+    check_missing_permissions,
+    format_settings_snippet,
+    infer_permissions,
+    load_current_permissions,
+)
+from cleave.core.reunify import (
+    aggregate_results,
+    generate_merge_md,
+    generate_review_md,
+    parse_task_result,
+    reunify_workspace,
+)
+from cleave.core.workspace import (
+    generate_manifest,
+    generate_siblings_yaml,
+    generate_task_file,
+    init_workspace,
+    reconstruct_context,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Assessment
+    "AssessmentResult",
+    "PatternMatch",
+    "assess_directive",
+    "calculate_complexity",
+    "detect_modifiers",
+    "effective_complexity",
+    "match_pattern",
+    # Conflicts
+    "Conflict",
+    "detect_conflicts",
+    # Permissions
+    "check_missing_permissions",
+    "format_settings_snippet",
+    "infer_permissions",
+    "load_current_permissions",
+    # Reunify
+    "aggregate_results",
+    "generate_merge_md",
+    "generate_review_md",
+    "parse_task_result",
+    "reunify_workspace",
+    # Workspace
+    "generate_manifest",
+    "generate_siblings_yaml",
+    "generate_task_file",
+    "init_workspace",
+    "reconstruct_context",
+]