htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- htmlgraph/.htmlgraph/.session-warning-state.json +6 -0
- htmlgraph/.htmlgraph/agents.json +72 -0
- htmlgraph/.htmlgraph/htmlgraph.db +0 -0
- htmlgraph/__init__.py +173 -17
- htmlgraph/__init__.pyi +123 -0
- htmlgraph/agent_detection.py +127 -0
- htmlgraph/agent_registry.py +45 -30
- htmlgraph/agents.py +160 -107
- htmlgraph/analytics/__init__.py +9 -2
- htmlgraph/analytics/cli.py +190 -51
- htmlgraph/analytics/cost_analyzer.py +391 -0
- htmlgraph/analytics/cost_monitor.py +664 -0
- htmlgraph/analytics/cost_reporter.py +675 -0
- htmlgraph/analytics/cross_session.py +617 -0
- htmlgraph/analytics/dependency.py +192 -100
- htmlgraph/analytics/pattern_learning.py +771 -0
- htmlgraph/analytics/session_graph.py +707 -0
- htmlgraph/analytics/strategic/__init__.py +80 -0
- htmlgraph/analytics/strategic/cost_optimizer.py +611 -0
- htmlgraph/analytics/strategic/pattern_detector.py +876 -0
- htmlgraph/analytics/strategic/preference_manager.py +709 -0
- htmlgraph/analytics/strategic/suggestion_engine.py +747 -0
- htmlgraph/analytics/work_type.py +190 -14
- htmlgraph/analytics_index.py +135 -51
- htmlgraph/api/__init__.py +3 -0
- htmlgraph/api/cost_alerts_websocket.py +416 -0
- htmlgraph/api/main.py +2498 -0
- htmlgraph/api/static/htmx.min.js +1 -0
- htmlgraph/api/static/style-redesign.css +1344 -0
- htmlgraph/api/static/style.css +1079 -0
- htmlgraph/api/templates/dashboard-redesign.html +1366 -0
- htmlgraph/api/templates/dashboard.html +794 -0
- htmlgraph/api/templates/partials/activity-feed-hierarchical.html +326 -0
- htmlgraph/api/templates/partials/activity-feed.html +1100 -0
- htmlgraph/api/templates/partials/agents-redesign.html +317 -0
- htmlgraph/api/templates/partials/agents.html +317 -0
- htmlgraph/api/templates/partials/event-traces.html +373 -0
- htmlgraph/api/templates/partials/features-kanban-redesign.html +509 -0
- htmlgraph/api/templates/partials/features.html +578 -0
- htmlgraph/api/templates/partials/metrics-redesign.html +346 -0
- htmlgraph/api/templates/partials/metrics.html +346 -0
- htmlgraph/api/templates/partials/orchestration-redesign.html +443 -0
- htmlgraph/api/templates/partials/orchestration.html +198 -0
- htmlgraph/api/templates/partials/spawners.html +375 -0
- htmlgraph/api/templates/partials/work-items.html +613 -0
- htmlgraph/api/websocket.py +538 -0
- htmlgraph/archive/__init__.py +24 -0
- htmlgraph/archive/bloom.py +234 -0
- htmlgraph/archive/fts.py +297 -0
- htmlgraph/archive/manager.py +583 -0
- htmlgraph/archive/search.py +244 -0
- htmlgraph/atomic_ops.py +560 -0
- htmlgraph/attribute_index.py +208 -0
- htmlgraph/bounded_paths.py +539 -0
- htmlgraph/builders/__init__.py +14 -0
- htmlgraph/builders/base.py +118 -29
- htmlgraph/builders/bug.py +150 -0
- htmlgraph/builders/chore.py +119 -0
- htmlgraph/builders/epic.py +150 -0
- htmlgraph/builders/feature.py +31 -6
- htmlgraph/builders/insight.py +195 -0
- htmlgraph/builders/metric.py +217 -0
- htmlgraph/builders/pattern.py +202 -0
- htmlgraph/builders/phase.py +162 -0
- htmlgraph/builders/spike.py +52 -19
- htmlgraph/builders/track.py +148 -72
- htmlgraph/cigs/__init__.py +81 -0
- htmlgraph/cigs/autonomy.py +385 -0
- htmlgraph/cigs/cost.py +475 -0
- htmlgraph/cigs/messages_basic.py +472 -0
- htmlgraph/cigs/messaging.py +365 -0
- htmlgraph/cigs/models.py +771 -0
- htmlgraph/cigs/pattern_storage.py +427 -0
- htmlgraph/cigs/patterns.py +503 -0
- htmlgraph/cigs/posttool_analyzer.py +234 -0
- htmlgraph/cigs/reporter.py +818 -0
- htmlgraph/cigs/tracker.py +317 -0
- htmlgraph/cli/.htmlgraph/.session-warning-state.json +6 -0
- htmlgraph/cli/.htmlgraph/agents.json +72 -0
- htmlgraph/cli/.htmlgraph/htmlgraph.db +0 -0
- htmlgraph/cli/__init__.py +42 -0
- htmlgraph/cli/__main__.py +6 -0
- htmlgraph/cli/analytics.py +1424 -0
- htmlgraph/cli/base.py +685 -0
- htmlgraph/cli/constants.py +206 -0
- htmlgraph/cli/core.py +954 -0
- htmlgraph/cli/main.py +147 -0
- htmlgraph/cli/models.py +475 -0
- htmlgraph/cli/templates/__init__.py +1 -0
- htmlgraph/cli/templates/cost_dashboard.py +399 -0
- htmlgraph/cli/work/__init__.py +239 -0
- htmlgraph/cli/work/browse.py +115 -0
- htmlgraph/cli/work/features.py +568 -0
- htmlgraph/cli/work/orchestration.py +676 -0
- htmlgraph/cli/work/report.py +728 -0
- htmlgraph/cli/work/sessions.py +466 -0
- htmlgraph/cli/work/snapshot.py +559 -0
- htmlgraph/cli/work/tracks.py +486 -0
- htmlgraph/cli_commands/__init__.py +1 -0
- htmlgraph/cli_commands/feature.py +195 -0
- htmlgraph/cli_framework.py +115 -0
- htmlgraph/collections/__init__.py +18 -0
- htmlgraph/collections/base.py +415 -98
- htmlgraph/collections/bug.py +53 -0
- htmlgraph/collections/chore.py +53 -0
- htmlgraph/collections/epic.py +53 -0
- htmlgraph/collections/feature.py +12 -26
- htmlgraph/collections/insight.py +100 -0
- htmlgraph/collections/metric.py +92 -0
- htmlgraph/collections/pattern.py +97 -0
- htmlgraph/collections/phase.py +53 -0
- htmlgraph/collections/session.py +194 -0
- htmlgraph/collections/spike.py +56 -16
- htmlgraph/collections/task_delegation.py +241 -0
- htmlgraph/collections/todo.py +511 -0
- htmlgraph/collections/traces.py +487 -0
- htmlgraph/config/cost_models.json +56 -0
- htmlgraph/config.py +190 -0
- htmlgraph/context_analytics.py +344 -0
- htmlgraph/converter.py +216 -28
- htmlgraph/cost_analysis/__init__.py +5 -0
- htmlgraph/cost_analysis/analyzer.py +438 -0
- htmlgraph/dashboard.html +2406 -307
- htmlgraph/dashboard.html.backup +6592 -0
- htmlgraph/dashboard.html.bak +7181 -0
- htmlgraph/dashboard.html.bak2 +7231 -0
- htmlgraph/dashboard.html.bak3 +7232 -0
- htmlgraph/db/__init__.py +38 -0
- htmlgraph/db/queries.py +790 -0
- htmlgraph/db/schema.py +1788 -0
- htmlgraph/decorators.py +317 -0
- htmlgraph/dependency_models.py +19 -2
- htmlgraph/deploy.py +142 -125
- htmlgraph/deployment_models.py +474 -0
- htmlgraph/docs/API_REFERENCE.md +841 -0
- htmlgraph/docs/HTTP_API.md +750 -0
- htmlgraph/docs/INTEGRATION_GUIDE.md +752 -0
- htmlgraph/docs/ORCHESTRATION_PATTERNS.md +717 -0
- htmlgraph/docs/README.md +532 -0
- htmlgraph/docs/__init__.py +77 -0
- htmlgraph/docs/docs_version.py +55 -0
- htmlgraph/docs/metadata.py +93 -0
- htmlgraph/docs/migrations.py +232 -0
- htmlgraph/docs/template_engine.py +143 -0
- htmlgraph/docs/templates/_sections/cli_reference.md.j2 +52 -0
- htmlgraph/docs/templates/_sections/core_concepts.md.j2 +29 -0
- htmlgraph/docs/templates/_sections/sdk_basics.md.j2 +69 -0
- htmlgraph/docs/templates/base_agents.md.j2 +78 -0
- htmlgraph/docs/templates/example_user_override.md.j2 +47 -0
- htmlgraph/docs/version_check.py +163 -0
- htmlgraph/edge_index.py +182 -27
- htmlgraph/error_handler.py +544 -0
- htmlgraph/event_log.py +100 -52
- htmlgraph/event_migration.py +13 -4
- htmlgraph/exceptions.py +49 -0
- htmlgraph/file_watcher.py +101 -28
- htmlgraph/find_api.py +75 -63
- htmlgraph/git_events.py +145 -63
- htmlgraph/graph.py +1122 -106
- htmlgraph/hooks/.htmlgraph/.session-warning-state.json +6 -0
- htmlgraph/hooks/.htmlgraph/agents.json +72 -0
- htmlgraph/hooks/.htmlgraph/index.sqlite +0 -0
- htmlgraph/hooks/__init__.py +45 -0
- htmlgraph/hooks/bootstrap.py +169 -0
- htmlgraph/hooks/cigs_pretool_enforcer.py +354 -0
- htmlgraph/hooks/concurrent_sessions.py +208 -0
- htmlgraph/hooks/context.py +350 -0
- htmlgraph/hooks/drift_handler.py +525 -0
- htmlgraph/hooks/event_tracker.py +1314 -0
- htmlgraph/hooks/git_commands.py +175 -0
- htmlgraph/hooks/hooks-config.example.json +12 -0
- htmlgraph/hooks/installer.py +343 -0
- htmlgraph/hooks/orchestrator.py +674 -0
- htmlgraph/hooks/orchestrator_reflector.py +223 -0
- htmlgraph/hooks/post-checkout.sh +28 -0
- htmlgraph/hooks/post-commit.sh +24 -0
- htmlgraph/hooks/post-merge.sh +26 -0
- htmlgraph/hooks/post_tool_use_failure.py +273 -0
- htmlgraph/hooks/post_tool_use_handler.py +257 -0
- htmlgraph/hooks/posttooluse.py +408 -0
- htmlgraph/hooks/pre-commit.sh +94 -0
- htmlgraph/hooks/pre-push.sh +28 -0
- htmlgraph/hooks/pretooluse.py +819 -0
- htmlgraph/hooks/prompt_analyzer.py +637 -0
- htmlgraph/hooks/session_handler.py +668 -0
- htmlgraph/hooks/session_summary.py +395 -0
- htmlgraph/hooks/state_manager.py +504 -0
- htmlgraph/hooks/subagent_detection.py +202 -0
- htmlgraph/hooks/subagent_stop.py +369 -0
- htmlgraph/hooks/task_enforcer.py +255 -0
- htmlgraph/hooks/task_validator.py +177 -0
- htmlgraph/hooks/validator.py +628 -0
- htmlgraph/ids.py +41 -27
- htmlgraph/index.d.ts +286 -0
- htmlgraph/learning.py +767 -0
- htmlgraph/mcp_server.py +69 -23
- htmlgraph/models.py +1586 -87
- htmlgraph/operations/README.md +62 -0
- htmlgraph/operations/__init__.py +79 -0
- htmlgraph/operations/analytics.py +339 -0
- htmlgraph/operations/bootstrap.py +289 -0
- htmlgraph/operations/events.py +244 -0
- htmlgraph/operations/fastapi_server.py +231 -0
- htmlgraph/operations/hooks.py +350 -0
- htmlgraph/operations/initialization.py +597 -0
- htmlgraph/operations/initialization.py.backup +228 -0
- htmlgraph/operations/server.py +303 -0
- htmlgraph/orchestration/__init__.py +58 -0
- htmlgraph/orchestration/claude_launcher.py +179 -0
- htmlgraph/orchestration/command_builder.py +72 -0
- htmlgraph/orchestration/headless_spawner.py +281 -0
- htmlgraph/orchestration/live_events.py +377 -0
- htmlgraph/orchestration/model_selection.py +327 -0
- htmlgraph/orchestration/plugin_manager.py +140 -0
- htmlgraph/orchestration/prompts.py +137 -0
- htmlgraph/orchestration/spawner_event_tracker.py +383 -0
- htmlgraph/orchestration/spawners/__init__.py +16 -0
- htmlgraph/orchestration/spawners/base.py +194 -0
- htmlgraph/orchestration/spawners/claude.py +173 -0
- htmlgraph/orchestration/spawners/codex.py +435 -0
- htmlgraph/orchestration/spawners/copilot.py +294 -0
- htmlgraph/orchestration/spawners/gemini.py +471 -0
- htmlgraph/orchestration/subprocess_runner.py +36 -0
- htmlgraph/orchestration/task_coordination.py +343 -0
- htmlgraph/orchestration.md +563 -0
- htmlgraph/orchestrator-system-prompt-optimized.txt +863 -0
- htmlgraph/orchestrator.py +669 -0
- htmlgraph/orchestrator_config.py +357 -0
- htmlgraph/orchestrator_mode.py +328 -0
- htmlgraph/orchestrator_validator.py +133 -0
- htmlgraph/parallel.py +646 -0
- htmlgraph/parser.py +160 -35
- htmlgraph/path_query.py +608 -0
- htmlgraph/pattern_matcher.py +636 -0
- htmlgraph/planning.py +147 -52
- htmlgraph/pydantic_models.py +476 -0
- htmlgraph/quality_gates.py +350 -0
- htmlgraph/query_builder.py +109 -72
- htmlgraph/query_composer.py +509 -0
- htmlgraph/reflection.py +443 -0
- htmlgraph/refs.py +344 -0
- htmlgraph/repo_hash.py +512 -0
- htmlgraph/repositories/__init__.py +292 -0
- htmlgraph/repositories/analytics_repository.py +455 -0
- htmlgraph/repositories/analytics_repository_standard.py +628 -0
- htmlgraph/repositories/feature_repository.py +581 -0
- htmlgraph/repositories/feature_repository_htmlfile.py +668 -0
- htmlgraph/repositories/feature_repository_memory.py +607 -0
- htmlgraph/repositories/feature_repository_sqlite.py +858 -0
- htmlgraph/repositories/filter_service.py +620 -0
- htmlgraph/repositories/filter_service_standard.py +445 -0
- htmlgraph/repositories/shared_cache.py +621 -0
- htmlgraph/repositories/shared_cache_memory.py +395 -0
- htmlgraph/repositories/track_repository.py +552 -0
- htmlgraph/repositories/track_repository_htmlfile.py +619 -0
- htmlgraph/repositories/track_repository_memory.py +508 -0
- htmlgraph/repositories/track_repository_sqlite.py +711 -0
- htmlgraph/routing.py +8 -19
- htmlgraph/scripts/deploy.py +1 -2
- htmlgraph/sdk/__init__.py +398 -0
- htmlgraph/sdk/__init__.pyi +14 -0
- htmlgraph/sdk/analytics/__init__.py +19 -0
- htmlgraph/sdk/analytics/engine.py +155 -0
- htmlgraph/sdk/analytics/helpers.py +178 -0
- htmlgraph/sdk/analytics/registry.py +109 -0
- htmlgraph/sdk/base.py +484 -0
- htmlgraph/sdk/constants.py +216 -0
- htmlgraph/sdk/core.pyi +308 -0
- htmlgraph/sdk/discovery.py +120 -0
- htmlgraph/sdk/help/__init__.py +12 -0
- htmlgraph/sdk/help/mixin.py +699 -0
- htmlgraph/sdk/mixins/__init__.py +15 -0
- htmlgraph/sdk/mixins/attribution.py +113 -0
- htmlgraph/sdk/mixins/mixin.py +410 -0
- htmlgraph/sdk/operations/__init__.py +12 -0
- htmlgraph/sdk/operations/mixin.py +427 -0
- htmlgraph/sdk/orchestration/__init__.py +17 -0
- htmlgraph/sdk/orchestration/coordinator.py +203 -0
- htmlgraph/sdk/orchestration/spawner.py +204 -0
- htmlgraph/sdk/planning/__init__.py +19 -0
- htmlgraph/sdk/planning/bottlenecks.py +93 -0
- htmlgraph/sdk/planning/mixin.py +211 -0
- htmlgraph/sdk/planning/parallel.py +186 -0
- htmlgraph/sdk/planning/queue.py +210 -0
- htmlgraph/sdk/planning/recommendations.py +87 -0
- htmlgraph/sdk/planning/smart_planning.py +319 -0
- htmlgraph/sdk/session/__init__.py +19 -0
- htmlgraph/sdk/session/continuity.py +57 -0
- htmlgraph/sdk/session/handoff.py +110 -0
- htmlgraph/sdk/session/info.py +309 -0
- htmlgraph/sdk/session/manager.py +103 -0
- htmlgraph/sdk/strategic/__init__.py +26 -0
- htmlgraph/sdk/strategic/mixin.py +563 -0
- htmlgraph/server.py +685 -180
- htmlgraph/services/__init__.py +10 -0
- htmlgraph/services/claiming.py +199 -0
- htmlgraph/session_hooks.py +300 -0
- htmlgraph/session_manager.py +1392 -175
- htmlgraph/session_registry.py +587 -0
- htmlgraph/session_state.py +436 -0
- htmlgraph/session_warning.py +201 -0
- htmlgraph/sessions/__init__.py +23 -0
- htmlgraph/sessions/handoff.py +756 -0
- htmlgraph/setup.py +34 -17
- htmlgraph/spike_index.py +143 -0
- htmlgraph/sync_docs.py +12 -15
- htmlgraph/system_prompts.py +450 -0
- htmlgraph/templates/AGENTS.md.template +366 -0
- htmlgraph/templates/CLAUDE.md.template +97 -0
- htmlgraph/templates/GEMINI.md.template +87 -0
- htmlgraph/templates/orchestration-view.html +350 -0
- htmlgraph/track_builder.py +146 -15
- htmlgraph/track_manager.py +69 -21
- htmlgraph/transcript.py +890 -0
- htmlgraph/transcript_analytics.py +699 -0
- htmlgraph/types.py +323 -0
- htmlgraph/validation.py +115 -0
- htmlgraph/watch.py +8 -5
- htmlgraph/work_type_utils.py +3 -2
- {htmlgraph-0.9.3.data → htmlgraph-0.27.5.data}/data/htmlgraph/dashboard.html +2406 -307
- htmlgraph-0.27.5.data/data/htmlgraph/templates/AGENTS.md.template +366 -0
- htmlgraph-0.27.5.data/data/htmlgraph/templates/CLAUDE.md.template +97 -0
- htmlgraph-0.27.5.data/data/htmlgraph/templates/GEMINI.md.template +87 -0
- {htmlgraph-0.9.3.dist-info → htmlgraph-0.27.5.dist-info}/METADATA +97 -64
- htmlgraph-0.27.5.dist-info/RECORD +337 -0
- {htmlgraph-0.9.3.dist-info → htmlgraph-0.27.5.dist-info}/entry_points.txt +1 -1
- htmlgraph/cli.py +0 -2688
- htmlgraph/sdk.py +0 -709
- htmlgraph-0.9.3.dist-info/RECORD +0 -61
- {htmlgraph-0.9.3.data → htmlgraph-0.27.5.data}/data/htmlgraph/styles.css +0 -0
- {htmlgraph-0.9.3.dist-info → htmlgraph-0.27.5.dist-info}/WHEEL +0 -0
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
# {{PROJECT_NAME}} - HtmlGraph Agent Documentation
|
|
2
|
+
|
|
3
|
+
**CRITICAL: AI agents must NEVER edit `.htmlgraph/` HTML files directly.**
|
|
4
|
+
|
|
5
|
+
Use the Python SDK, API, or CLI instead. This ensures all HTML is validated through Pydantic + justhtml.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Quick Start (Python SDK)
|
|
10
|
+
|
|
11
|
+
```python
|
|
12
|
+
from htmlgraph import SDK
|
|
13
|
+
|
|
14
|
+
# Initialize (auto-discovers .htmlgraph directory)
|
|
15
|
+
sdk = SDK(agent="{{AGENT_NAME}}")
|
|
16
|
+
|
|
17
|
+
# Get project status
|
|
18
|
+
print(sdk.summary(max_items=10))
|
|
19
|
+
|
|
20
|
+
# Create a feature
|
|
21
|
+
feature = sdk.features.create("New Feature") \
|
|
22
|
+
.set_priority("high") \
|
|
23
|
+
.set_description("Feature description here") \
|
|
24
|
+
.add_steps([
|
|
25
|
+
"Step 1",
|
|
26
|
+
"Step 2",
|
|
27
|
+
"Step 3"
|
|
28
|
+
]) \
|
|
29
|
+
.save()
|
|
30
|
+
|
|
31
|
+
print(f"Created: {feature.id}")
|
|
32
|
+
|
|
33
|
+
# Work on it
|
|
34
|
+
with sdk.features.edit(feature.id) as f:
|
|
35
|
+
f.status = "in-progress"
|
|
36
|
+
f.agent_assigned = "{{AGENT_NAME}}"
|
|
37
|
+
f.steps[0].completed = True
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Core Principle: NEVER Edit HTML Directly
|
|
43
|
+
|
|
44
|
+
❌ **FORBIDDEN:**
|
|
45
|
+
```python
|
|
46
|
+
# NEVER DO THIS
|
|
47
|
+
with open(".htmlgraph/features/feature-123.html", "w") as f:
|
|
48
|
+
f.write("<html>...</html>")
|
|
49
|
+
|
|
50
|
+
# NEVER DO THIS
|
|
51
|
+
Edit("/path/to/.htmlgraph/features/feature-123.html", ...)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
✅ **REQUIRED - Use SDK/API/CLI:**
|
|
55
|
+
```python
|
|
56
|
+
# SDK (recommended)
|
|
57
|
+
with sdk.features.edit("feature-123") as f:
|
|
58
|
+
f.status = "done"
|
|
59
|
+
|
|
60
|
+
# API
|
|
61
|
+
curl -X PATCH http://localhost:8080/api/features/feature-123 \
|
|
62
|
+
-H "Content-Type: application/json" \
|
|
63
|
+
-d '{"status": "done"}'
|
|
64
|
+
|
|
65
|
+
# CLI
|
|
66
|
+
htmlgraph feature complete feature-123
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Why this matters:**
|
|
70
|
+
- Direct edits bypass Pydantic validation
|
|
71
|
+
- Bypass justhtml HTML generation
|
|
72
|
+
- Break SQLite index sync
|
|
73
|
+
- Can corrupt graph structure
|
|
74
|
+
- Skip event logging
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Python SDK (Recommended)
|
|
79
|
+
|
|
80
|
+
### Installation
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
pip install htmlgraph
|
|
84
|
+
# or
|
|
85
|
+
uv pip install htmlgraph
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Initialization
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from htmlgraph import SDK
|
|
92
|
+
|
|
93
|
+
# Auto-discover .htmlgraph directory
|
|
94
|
+
sdk = SDK(agent="{{AGENT_NAME}}")
|
|
95
|
+
|
|
96
|
+
# Or specify path
|
|
97
|
+
sdk = SDK(directory="/path/to/.htmlgraph", agent="{{AGENT_NAME}}")
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Get Oriented
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
# Project summary
|
|
104
|
+
summary = sdk.summary(max_items=10)
|
|
105
|
+
print(summary)
|
|
106
|
+
|
|
107
|
+
# My workload
|
|
108
|
+
workload = sdk.my_work()
|
|
109
|
+
print(f"In progress: {workload['in_progress']}")
|
|
110
|
+
print(f"Completed: {workload['completed']}")
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Create Features
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
# Fluent builder pattern
|
|
117
|
+
feature = sdk.features.create("Implement Dark Mode") \
|
|
118
|
+
.set_priority("high") \
|
|
119
|
+
.set_description("Add dark theme toggle to settings") \
|
|
120
|
+
.add_steps([
|
|
121
|
+
"Design color palette",
|
|
122
|
+
"Create CSS variables",
|
|
123
|
+
"Implement toggle component",
|
|
124
|
+
"Add persistence (localStorage)",
|
|
125
|
+
"Test across pages"
|
|
126
|
+
]) \
|
|
127
|
+
.save()
|
|
128
|
+
|
|
129
|
+
print(f"Created: {feature.id}")
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Work on Features
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
# Context manager auto-saves on exit
|
|
136
|
+
with sdk.features.edit("feature-001") as f:
|
|
137
|
+
f.status = "in-progress"
|
|
138
|
+
f.agent_assigned = "{{AGENT_NAME}}"
|
|
139
|
+
f.steps[0].completed = True
|
|
140
|
+
f.steps[0].agent = "{{AGENT_NAME}}"
|
|
141
|
+
|
|
142
|
+
# Check if all steps done
|
|
143
|
+
with sdk.features.edit("feature-001") as f:
|
|
144
|
+
all_done = all(s.completed for s in f.steps)
|
|
145
|
+
if all_done:
|
|
146
|
+
f.status = "done"
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Query Features
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
# Declarative filtering
|
|
153
|
+
high_priority = sdk.features.where(status="todo", priority="high")
|
|
154
|
+
my_work = sdk.features.where(assigned_to="{{AGENT_NAME}}", status="in-progress")
|
|
155
|
+
track_features = sdk.features.where(track="auth-track")
|
|
156
|
+
|
|
157
|
+
# Get all
|
|
158
|
+
all_features = sdk.features.all()
|
|
159
|
+
|
|
160
|
+
# Get by ID
|
|
161
|
+
feature = sdk.features.get("feature-001")
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Batch Operations
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
# Mark multiple as done
|
|
168
|
+
count = sdk.features.mark_done([
|
|
169
|
+
"feature-001",
|
|
170
|
+
"feature-002",
|
|
171
|
+
"feature-003"
|
|
172
|
+
])
|
|
173
|
+
print(f"Marked {count} features as done")
|
|
174
|
+
|
|
175
|
+
# Assign multiple to agent
|
|
176
|
+
count = sdk.features.assign(
|
|
177
|
+
["feature-004", "feature-005"],
|
|
178
|
+
agent="{{AGENT_NAME}}"
|
|
179
|
+
)
|
|
180
|
+
print(f"Assigned {count} features to {{AGENT_NAME}}")
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## CLI (Alternative)
|
|
186
|
+
|
|
187
|
+
### Check Status
|
|
188
|
+
```bash
|
|
189
|
+
htmlgraph status
|
|
190
|
+
htmlgraph feature list
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Start Feature
|
|
194
|
+
```bash
|
|
195
|
+
htmlgraph feature start <feature-id>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Complete Feature
|
|
199
|
+
```bash
|
|
200
|
+
htmlgraph feature complete <feature-id>
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Server
|
|
204
|
+
```bash
|
|
205
|
+
htmlgraph serve
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Best Practices for AI Agents
|
|
211
|
+
|
|
212
|
+
### 1. Always Use SDK in Python Code
|
|
213
|
+
|
|
214
|
+
```python
|
|
215
|
+
# ✅ GOOD
|
|
216
|
+
from htmlgraph import SDK
|
|
217
|
+
sdk = SDK(agent="{{AGENT_NAME}}")
|
|
218
|
+
feature = sdk.features.create("Title").save()
|
|
219
|
+
|
|
220
|
+
# ❌ BAD - Don't use low-level API directly
|
|
221
|
+
from htmlgraph import HtmlGraph, Node
|
|
222
|
+
graph = HtmlGraph(".htmlgraph/features")
|
|
223
|
+
node = Node(id="...", title="...")
|
|
224
|
+
graph.add(node)
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### 2. Use Context Managers (Auto-Save)
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
# ✅ GOOD - Auto-saves on exit
|
|
231
|
+
with sdk.features.edit("feature-001") as f:
|
|
232
|
+
f.status = "done"
|
|
233
|
+
|
|
234
|
+
# ❌ BAD - Easy to forget to save
|
|
235
|
+
feature = sdk.features.get("feature-001")
|
|
236
|
+
feature.status = "done"
|
|
237
|
+
# Forgot to call sdk._graph.update(feature)!
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### 3. Use Declarative Queries
|
|
241
|
+
|
|
242
|
+
```python
|
|
243
|
+
# ✅ GOOD
|
|
244
|
+
todos = sdk.features.where(status="todo", priority="high")
|
|
245
|
+
|
|
246
|
+
# ❌ BAD - Manual filtering
|
|
247
|
+
todos = [
|
|
248
|
+
f for f in sdk.features.all()
|
|
249
|
+
if f.status == "todo" and f.priority == "high"
|
|
250
|
+
]
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### 4. Use Batch Operations
|
|
254
|
+
|
|
255
|
+
```python
|
|
256
|
+
# ✅ GOOD - Single operation
|
|
257
|
+
sdk.features.mark_done(["feat-001", "feat-002", "feat-003"])
|
|
258
|
+
|
|
259
|
+
# ❌ BAD - Multiple operations
|
|
260
|
+
for id in ["feat-001", "feat-002", "feat-003"]:
|
|
261
|
+
with sdk.features.edit(id) as f:
|
|
262
|
+
f.status = "done"
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### 5. Check Status Before Working
|
|
266
|
+
|
|
267
|
+
```python
|
|
268
|
+
# Get orientation
|
|
269
|
+
print(sdk.summary())
|
|
270
|
+
|
|
271
|
+
# Check your workload
|
|
272
|
+
workload = sdk.my_work()
|
|
273
|
+
if workload['in_progress'] > 5:
|
|
274
|
+
print("Already at capacity!")
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## Complete Workflow Example
|
|
280
|
+
|
|
281
|
+
```python
|
|
282
|
+
from htmlgraph import SDK
|
|
283
|
+
|
|
284
|
+
def ai_agent_workflow():
|
|
285
|
+
"""Realistic AI agent workflow."""
|
|
286
|
+
|
|
287
|
+
# 1. Initialize
|
|
288
|
+
sdk = SDK(agent="{{AGENT_NAME}}")
|
|
289
|
+
|
|
290
|
+
# 2. Get oriented
|
|
291
|
+
print("=== Project Summary ===")
|
|
292
|
+
print(sdk.summary(max_items=10))
|
|
293
|
+
|
|
294
|
+
# 3. Check workload
|
|
295
|
+
workload = sdk.my_work()
|
|
296
|
+
print(f"\nMy Workload:")
|
|
297
|
+
print(f" In progress: {workload['in_progress']}")
|
|
298
|
+
print(f" Completed: {workload['completed']}")
|
|
299
|
+
|
|
300
|
+
if workload['in_progress'] > 5:
|
|
301
|
+
print("\n⚠️ Already at capacity!")
|
|
302
|
+
return
|
|
303
|
+
|
|
304
|
+
# 4. Get next task
|
|
305
|
+
task = sdk.next_task(priority="high", auto_claim=True)
|
|
306
|
+
|
|
307
|
+
if not task:
|
|
308
|
+
print("\n✅ No high-priority tasks available")
|
|
309
|
+
return
|
|
310
|
+
|
|
311
|
+
print(f"\n=== Working on: {task.title} ===")
|
|
312
|
+
|
|
313
|
+
# 5. Work on task
|
|
314
|
+
with sdk.features.edit(task.id) as feature:
|
|
315
|
+
print(f"\nSteps:")
|
|
316
|
+
for i, step in enumerate(feature.steps):
|
|
317
|
+
if step.completed:
|
|
318
|
+
print(f" ✅ {step.description}")
|
|
319
|
+
else:
|
|
320
|
+
print(f" ⏳ {step.description}")
|
|
321
|
+
|
|
322
|
+
# Do the work here...
|
|
323
|
+
# (implementation details)
|
|
324
|
+
|
|
325
|
+
# Mark step complete
|
|
326
|
+
step.completed = True
|
|
327
|
+
step.agent = "{{AGENT_NAME}}"
|
|
328
|
+
print(f" ✓ Completed: {step.description}")
|
|
329
|
+
break
|
|
330
|
+
|
|
331
|
+
# Check if all done
|
|
332
|
+
all_done = all(s.completed for s in feature.steps)
|
|
333
|
+
if all_done:
|
|
334
|
+
feature.status = "done"
|
|
335
|
+
print(f"\n✅ Feature complete: {feature.id}")
|
|
336
|
+
|
|
337
|
+
if __name__ == "__main__":
|
|
338
|
+
ai_agent_workflow()
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Documentation
|
|
344
|
+
|
|
345
|
+
For full documentation, see:
|
|
346
|
+
- **HtmlGraph Documentation**: https://github.com/Shakes-tzd/htmlgraph
|
|
347
|
+
- **Dashboard**: Run `htmlgraph serve` and open http://localhost:8080
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## Project-Specific Notes
|
|
352
|
+
|
|
353
|
+
<!-- Add your project-specific agent instructions here -->
|
|
354
|
+
|
|
355
|
+
### Team Structure
|
|
356
|
+
|
|
357
|
+
- **Agent**: {{AGENT_NAME}}
|
|
358
|
+
- **Project**: {{PROJECT_NAME}}
|
|
359
|
+
|
|
360
|
+
### Custom Workflows
|
|
361
|
+
|
|
362
|
+
<!-- Document any project-specific workflows here -->
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
*Generated by HtmlGraph {{VERSION}}*
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# {{PROJECT_NAME}} - Claude-Specific Notes
|
|
2
|
+
|
|
3
|
+
## Quick Reference
|
|
4
|
+
|
|
5
|
+
**→ See [AGENTS.md](./AGENTS.md) for complete SDK documentation**
|
|
6
|
+
|
|
7
|
+
This file contains Claude-specific notes and references the main agent documentation.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Core Principle
|
|
12
|
+
|
|
13
|
+
**CRITICAL: NEVER edit `.htmlgraph/` HTML files directly.**
|
|
14
|
+
|
|
15
|
+
Use the SDK instead:
|
|
16
|
+
```python
|
|
17
|
+
from htmlgraph import SDK
|
|
18
|
+
sdk = SDK(agent="claude")
|
|
19
|
+
sdk.features.complete("feat-62f83856")
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Full details in [AGENTS.md](./AGENTS.md)
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Claude-Specific Best Practices
|
|
27
|
+
|
|
28
|
+
### 1. Use TodoWrite for Task Tracking
|
|
29
|
+
|
|
30
|
+
Claude Code has a TodoWrite tool for tracking multi-step tasks. Use it when:
|
|
31
|
+
- Task requires 3+ distinct steps
|
|
32
|
+
- Complex implementation with dependencies
|
|
33
|
+
- User provides multiple tasks
|
|
34
|
+
|
|
35
|
+
### 2. Leverage Read/Edit/Bash Tools
|
|
36
|
+
|
|
37
|
+
Claude Code provides specialized file tools:
|
|
38
|
+
- **Read**: Read file contents
|
|
39
|
+
- **Edit**: Make exact string replacements
|
|
40
|
+
- **Bash**: Run shell commands
|
|
41
|
+
- **Grep**: Search file contents
|
|
42
|
+
|
|
43
|
+
### 3. Session Tracking
|
|
44
|
+
|
|
45
|
+
HtmlGraph automatically tracks Claude Code sessions via git hooks. No manual tracking needed.
|
|
46
|
+
|
|
47
|
+
### 4. Transcript Integration
|
|
48
|
+
|
|
49
|
+
Claude Code transcripts are automatically linked to features when you work on a git branch:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# HtmlGraph auto-links transcripts by branch name
|
|
53
|
+
htmlgraph transcript auto-link
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Getting Started
|
|
59
|
+
|
|
60
|
+
1. **Initialize SDK:**
|
|
61
|
+
```python
|
|
62
|
+
from htmlgraph import SDK
|
|
63
|
+
sdk = SDK(agent="claude")
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
2. **Check project status:**
|
|
67
|
+
```python
|
|
68
|
+
print(sdk.summary())
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
3. **Get next task:**
|
|
72
|
+
```python
|
|
73
|
+
task = sdk.next_task(priority="high", auto_claim=True)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
4. **Work on it using SDK** (NEVER edit HTML directly)
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Common Patterns
|
|
81
|
+
|
|
82
|
+
See [AGENTS.md](./AGENTS.md) for:
|
|
83
|
+
- ✅ Python SDK usage
|
|
84
|
+
- ✅ Feature creation and management
|
|
85
|
+
- ✅ Query and filtering
|
|
86
|
+
- ✅ Batch operations
|
|
87
|
+
- ✅ Workflow examples
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Project-Specific Notes
|
|
92
|
+
|
|
93
|
+
<!-- Add Claude-specific notes for your project here -->
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
*Generated by HtmlGraph {{VERSION}}*
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# {{PROJECT_NAME}} - Gemini-Specific Notes
|
|
2
|
+
|
|
3
|
+
## Quick Reference
|
|
4
|
+
|
|
5
|
+
**→ See [AGENTS.md](./AGENTS.md) for complete SDK documentation**
|
|
6
|
+
|
|
7
|
+
This file contains Gemini-specific notes and references the main agent documentation.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Core Principle
|
|
12
|
+
|
|
13
|
+
**CRITICAL: NEVER edit `.htmlgraph/` HTML files directly.**
|
|
14
|
+
|
|
15
|
+
Use the SDK instead:
|
|
16
|
+
```python
|
|
17
|
+
from htmlgraph import SDK
|
|
18
|
+
sdk = SDK(agent="gemini")
|
|
19
|
+
sdk.features.complete("feat-62f83856")
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Full details in [AGENTS.md](./AGENTS.md)
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Gemini-Specific Best Practices
|
|
27
|
+
|
|
28
|
+
### 1. Use Code Execution for Testing
|
|
29
|
+
|
|
30
|
+
Gemini has built-in code execution. Use it to:
|
|
31
|
+
- Test SDK operations before committing
|
|
32
|
+
- Verify feature status
|
|
33
|
+
- Run quick analytics
|
|
34
|
+
|
|
35
|
+
### 2. Function Calling
|
|
36
|
+
|
|
37
|
+
Gemini excels at function calling. Leverage this for:
|
|
38
|
+
- Structured SDK operations
|
|
39
|
+
- Batch updates
|
|
40
|
+
- Analytics queries
|
|
41
|
+
|
|
42
|
+
### 3. Session Management
|
|
43
|
+
|
|
44
|
+
HtmlGraph tracks Gemini sessions automatically. No manual intervention needed.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Getting Started
|
|
49
|
+
|
|
50
|
+
1. **Initialize SDK:**
|
|
51
|
+
```python
|
|
52
|
+
from htmlgraph import SDK
|
|
53
|
+
sdk = SDK(agent="gemini")
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
2. **Check project status:**
|
|
57
|
+
```python
|
|
58
|
+
print(sdk.summary())
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
3. **Get next task:**
|
|
62
|
+
```python
|
|
63
|
+
task = sdk.next_task(priority="high", auto_claim=True)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
4. **Work on it using SDK** (NEVER edit HTML directly)
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Common Patterns
|
|
71
|
+
|
|
72
|
+
See [AGENTS.md](./AGENTS.md) for:
|
|
73
|
+
- ✅ Python SDK usage
|
|
74
|
+
- ✅ Feature creation and management
|
|
75
|
+
- ✅ Query and filtering
|
|
76
|
+
- ✅ Batch operations
|
|
77
|
+
- ✅ Workflow examples
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Project-Specific Notes
|
|
82
|
+
|
|
83
|
+
<!-- Add Gemini-specific notes for your project here -->
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
*Generated by HtmlGraph {{VERSION}}*
|