Skip to content

Commit fc203fb

Browse files
Caik PigossoCaik Pigosso
Caik Pigosso
authored and
Caik Pigosso
committed
feat: Initial release of LessTokens SDK Python
- Complete SDK implementation with support for OpenAI, Anthropic, Google, and DeepSeek - 98% test coverage with 112 passing tests - Full type hints and type safety - Streaming support for real-time responses - Multi-turn conversation support - Comprehensive error handling and retry logic - Complete documentation (API, Architecture, Integration guides) - Ready for PyPI publication
0 parents  commit fc203fb

83 files changed

Lines changed: 13051 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cursor/commands/rulebook-task-apply.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
name: /rulebook-task-apply
3+
id: rulebook-task-apply
4+
category: Rulebook
5+
description: Implement an approved Rulebook task and keep tasks checklist in sync.
6+
---
7+
<!-- RULEBOOK:START -->
8+
**Guardrails**
9+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10+
- Keep changes tightly scoped to the requested outcome.
11+
- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines.
12+
- **CRITICAL**: Update `tasks.md` IMMEDIATELY after completing and testing each implementation step.
13+
14+
**Steps**
15+
Track these steps as TODOs and complete them one by one.
16+
17+
1. **Read Task Details**:
18+
```bash
19+
rulebook task show <task-id>
20+
```
21+
Read `proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
22+
23+
2. **Follow Priority Order (MANDATORY)**:
24+
- **Tests** (HIGHEST PRIORITY) - Write tests first
25+
- **Coverage Verification** (CRITICAL) - Verify coverage ≥95%
26+
- **Update Task Status** (MANDATORY) - Mark completed items as `[x]` in `tasks.md`
27+
- **Next Task** (Only after above steps)
28+
29+
3. **Work Through Tasks Sequentially**:
30+
- Work through `tasks.md` checklist item by item
31+
- Keep edits minimal and focused on the requested change
32+
- Follow priority order (most critical first)
33+
34+
4. **After Each Implementation Step**:
35+
- ✅ Implement the feature
36+
- ✅ Test the implementation
37+
- ✅ Verify test coverage (run `npm test -- --coverage`)
38+
- ✅ Update `tasks.md` IMMEDIATELY (mark as `[x]`)
39+
- ✅ Commit locally (backup)
40+
- ✅ Only then proceed to next task
41+
42+
5. **Update Tasks Checklist**:
43+
After completing and testing each item:
44+
```markdown
45+
## 1. Implementation Phase
46+
- [x] 1.1 Create task manager module <!-- tested, coverage: 95% -->
47+
- [x] 1.2 Add validation logic <!-- tested, coverage: 92%, status: complete -->
48+
- [ ] 1.3 Add archive functionality <!-- next: will start after status update -->
49+
```
50+
51+
6. **Confirm Completion**:
52+
- Make sure every item in `tasks.md` is finished
53+
- All tests pass
54+
- Coverage meets thresholds
55+
- Documentation updated
56+
57+
7. **Update Checklist After All Work**:
58+
- Mark each completed task as `[x]`
59+
- Add comments with test status and coverage
60+
- Reflect reality in the checklist
61+
62+
**Reference**
63+
- Use `rulebook task show <task-id>` when additional context is required
64+
- Use `rulebook task validate <task-id>` to check format before archiving
65+
- See `/rulebook/RULEBOOK.md` for complete task management guidelines and priority order
66+
<!-- RULEBOOK:END -->
67+

‎.cursor/commands/rulebook-task-archive.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
name: /rulebook-task-archive
3+
id: rulebook-task-archive
4+
category: Rulebook
5+
description: Archive a completed Rulebook task and apply spec deltas to main specifications.
6+
---
7+
<!-- RULEBOOK:START -->
8+
**Guardrails**
9+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10+
- Keep changes tightly scoped to the requested outcome.
11+
- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines.
12+
13+
**Steps**
14+
1. **Verify Task Completion**:
15+
- All items in `tasks.md` must be marked as `[x]`
16+
- All tests must pass
17+
- Code review complete (if applicable)
18+
- Documentation updated (README, CHANGELOG, specs)
19+
20+
2. **Run Quality Checks**:
21+
```bash
22+
npm test
23+
npm run lint
24+
npm run type-check
25+
npm run build
26+
```
27+
Ensure all checks pass before archiving.
28+
29+
3. **Validate Task Format**:
30+
```bash
31+
rulebook task validate <task-id>
32+
```
33+
Must pass all format checks.
34+
35+
4. **Archive Task**:
36+
```bash
37+
rulebook task archive <task-id>
38+
```
39+
Or without prompts:
40+
```bash
41+
rulebook task archive <task-id> --skip-validation
42+
```
43+
(Only use `--skip-validation` if you're certain the task is valid)
44+
45+
5. **Archive Process**:
46+
- Validates task format (unless skipped)
47+
- Checks task completion status
48+
- Applies spec deltas to main specifications
49+
- Moves task to `/rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
50+
- Updates related specifications
51+
52+
6. **Verify Archive**:
53+
```bash
54+
rulebook task list --archived
55+
```
56+
Task should appear in archived list.
57+
58+
7. **Post-Archive Actions**:
59+
- Ensure spec deltas are applied to main specifications
60+
- Update CHANGELOG.md with the change
61+
- Document any breaking changes
62+
- Create migration guides (if needed)
63+
- Unblock related tasks (if any)
64+
65+
**Reference**
66+
- Use `rulebook task list --archived` to see archived tasks
67+
- Use `rulebook task show <task-id>` to view task details
68+
- See `/rulebook/RULEBOOK.md` for complete task management guidelines
69+
<!-- RULEBOOK:END -->
70+

‎.cursor/commands/rulebook-task-create.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
name: /rulebook-task-create
3+
id: rulebook-task-create
4+
category: Rulebook
5+
description: Create a new Rulebook task following OpenSpec-compatible format with Context7 MCP validation.
6+
---
7+
<!-- RULEBOOK:START -->
8+
**Guardrails**
9+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10+
- Keep changes tightly scoped to the requested outcome.
11+
- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines and format requirements.
12+
- **CRITICAL**: Context7 MCP is REQUIRED for task creation to ensure correct OpenSpec-compatible format.
13+
- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
14+
15+
**Steps**
16+
1. **Check Context7 MCP (MANDATORY)**: Query Context7 for OpenSpec documentation to get the official format:
17+
```
18+
@Context7 /fission-ai/openspec task creation format spec structure
19+
```
20+
Review official format requirements: spec delta format, requirement structure, scenario formatting, delta headers (ADDED/MODIFIED/REMOVED/RENAMED).
21+
22+
2. **Explore Current State**:
23+
- Run `rulebook task list` to see existing tasks
24+
- Review related code or docs (e.g., via `rg`/`ls`) to understand current behavior
25+
- Note any gaps that require clarification
26+
27+
3. **Choose Task ID**: Use verb-led kebab-case (e.g., `add-feature`, `update-api`, `refactor-module`). Must be unique.
28+
29+
4. **Create Task Structure**:
30+
```bash
31+
rulebook task create <task-id>
32+
```
33+
This creates `/rulebook/tasks/<task-id>/` with:
34+
- `proposal.md` - Why and what changes
35+
- `tasks.md` - Implementation checklist
36+
- `specs/` - Directory for spec deltas
37+
38+
5. **Write Proposal** (`proposal.md`):
39+
- **Why**: Minimum 20 characters explaining why this change is needed
40+
- **What Changes**: Detailed description of what will change
41+
- **Impact**: Affected specs, code, breaking changes, user benefits
42+
43+
6. **Write Tasks Checklist** (`tasks.md`):
44+
- Organize by phases (Implementation, Testing, Documentation)
45+
- Use checkbox format: `- [ ] Task description`
46+
- Include validation steps (tests, coverage checks)
47+
48+
7. **Write Spec Delta** (`specs/<module>/spec.md`):
49+
- Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers
50+
- Requirements MUST use `### Requirement: [Name]` with SHALL/MUST keywords
51+
- Scenarios MUST use `#### Scenario:` (4 hashtags, NOT 3)
52+
- Scenarios MUST use Given/When/Then structure
53+
- Example:
54+
```markdown
55+
## ADDED Requirements
56+
57+
### Requirement: Feature Name
58+
The system SHALL do something specific and testable.
59+
60+
#### Scenario: Scenario Name
61+
Given some precondition
62+
When an action occurs
63+
Then an expected outcome happens
64+
```
65+
66+
8. **Validate Task**:
67+
```bash
68+
rulebook task validate <task-id>
69+
```
70+
Fix any validation errors before proceeding.
71+
72+
9. **Verify Format**:
73+
- Purpose section: ≥20 characters ✅
74+
- Requirements: Contain SHALL or MUST ✅
75+
- Scenarios: Use `#### Scenario:` (4 hashtags) ✅
76+
- Scenarios: Use Given/When/Then structure ✅
77+
- Delta headers: Use ADDED/MODIFIED/REMOVED/RENAMED ✅
78+
79+
**Reference**
80+
- See `/rulebook/RULEBOOK.md` for complete task management guidelines
81+
- Use `rulebook task show <task-id>` to view task details
82+
- Use `rulebook task list` to see all tasks
83+
- Search existing requirements with `rg -n "Requirement:|Scenario:" rulebook/tasks` before writing new ones
84+
- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities
85+
86+
**Common Pitfalls to Avoid**
87+
- ❌ Using 3 hashtags for scenarios (`### Scenario:`) - MUST use 4 (`#### Scenario:`)
88+
- ❌ Missing SHALL/MUST keywords in requirements
89+
- ❌ Using bullet points for scenarios instead of Given/When/Then
90+
- ❌ Purpose section too short (<20 characters)
91+
- ❌ Wrong delta headers (use ADDED/MODIFIED/REMOVED/RENAMED, not "New Requirements" or "Changes")
92+
<!-- RULEBOOK:END -->
93+

‎.cursor/commands/rulebook-task-list.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: /rulebook-task-list
3+
id: rulebook-task-list
4+
category: Rulebook
5+
description: List all Rulebook tasks (active and optionally archived).
6+
---
7+
<!-- RULEBOOK:START -->
8+
**Guardrails**
9+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10+
- Keep changes tightly scoped to the requested outcome.
11+
- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines.
12+
13+
**Steps**
14+
1. **List Active Tasks**:
15+
```bash
16+
rulebook task list
17+
```
18+
Shows all active tasks with their status (pending, in-progress, completed, blocked).
19+
20+
2. **List Including Archived**:
21+
```bash
22+
rulebook task list --archived
23+
```
24+
Shows both active and archived tasks.
25+
26+
3. **Review Task Status**:
27+
- **pending**: Task not started
28+
- **in-progress**: Task being worked on
29+
- **completed**: Task finished (ready for archive)
30+
- **blocked**: Task blocked by dependency
31+
32+
4. **Select Task to Work On**:
33+
- Choose task with highest priority
34+
- Check task status before starting
35+
- Verify task is not blocked
36+
37+
**Reference**
38+
- Use `rulebook task show <task-id>` to view task details
39+
- Use `rulebook task validate <task-id>` to check task format
40+
- See `/rulebook/RULEBOOK.md` for complete task management guidelines
41+
<!-- RULEBOOK:END -->
42+

‎.cursor/commands/rulebook-task-show.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: /rulebook-task-show
3+
id: rulebook-task-show
4+
category: Rulebook
5+
description: Show detailed information about a specific Rulebook task.
6+
---
7+
<!-- RULEBOOK:START -->
8+
**Guardrails**
9+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10+
- Keep changes tightly scoped to the requested outcome.
11+
- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines.
12+
13+
**Steps**
14+
1. **Show Task Details**:
15+
```bash
16+
rulebook task show <task-id>
17+
```
18+
Displays:
19+
- Task ID and title
20+
- Status (pending, in-progress, completed, blocked)
21+
- Created and updated dates
22+
- Archive date (if archived)
23+
- Proposal summary
24+
- Spec files list
25+
26+
2. **Review Proposal**:
27+
- Read `proposal.md` to understand why and what changes
28+
- Check impact assessment
29+
- Verify breaking changes are documented
30+
31+
3. **Review Tasks Checklist**:
32+
- Check `tasks.md` for implementation checklist
33+
- Identify completed items (`[x]`)
34+
- Identify pending items (`[ ]`)
35+
- Follow priority order (most critical first)
36+
37+
4. **Review Spec Deltas**:
38+
- Check `specs/*/spec.md` files
39+
- Verify format compliance (SHALL/MUST, 4 hashtags for scenarios)
40+
- Understand requirements and scenarios
41+
42+
5. **Check Task Status**:
43+
- Verify task is not blocked
44+
- Check if task is ready for implementation
45+
- Confirm all prerequisites are met
46+
47+
**Reference**
48+
- Use `rulebook task list` to see all tasks
49+
- Use `rulebook task validate <task-id>` to check task format
50+
- See `/rulebook/RULEBOOK.md` for complete task management guidelines
51+
<!-- RULEBOOK:END -->
52+

‎.cursor/commands/rulebook-task-validate.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: /rulebook-task-validate
3+
id: rulebook-task-validate
4+
category: Rulebook
5+
description: Validate Rulebook task format against OpenSpec-compatible requirements.
6+
---
7+
<!-- RULEBOOK:START -->
8+
**Guardrails**
9+
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
10+
- Keep changes tightly scoped to the requested outcome.
11+
- Refer to `/rulebook/RULEBOOK.md` for complete task management guidelines and format requirements.
12+
13+
**Steps**
14+
1. **Validate Task Format**:
15+
```bash
16+
rulebook task validate <task-id>
17+
```
18+
Checks:
19+
- Purpose section length (≥20 characters)
20+
- Requirement keywords (SHALL/MUST)
21+
- Scenario format (4 hashtags, not 3)
22+
- Given/When/Then structure
23+
- Delta headers format (ADDED/MODIFIED/REMOVED/RENAMED)
24+
25+
2. **Review Validation Results**:
26+
- **Errors**: Must be fixed before proceeding
27+
- **Warnings**: Should be addressed but not blocking
28+
29+
3. **Fix Format Issues**:
30+
- **Purpose too short**: Expand "Why" section to ≥20 characters
31+
- **Missing SHALL/MUST**: Add SHALL or MUST keyword to requirements
32+
- **Wrong scenario format**: Change `### Scenario:` to `#### Scenario:` (4 hashtags)
33+
- **Missing Given/When/Then**: Replace bullet points with Given/When/Then structure
34+
- **Wrong delta headers**: Use ADDED/MODIFIED/REMOVED/RENAMED, not "New Requirements"
35+
36+
4. **Re-validate After Fixes**:
37+
```bash
38+
rulebook task validate <task-id>
39+
```
40+
Ensure all errors are resolved.
41+
42+
5. **Common Format Errors**:
43+
- ❌ `### Scenario:` (3 hashtags) → ✅ `#### Scenario:` (4 hashtags)
44+
- ❌ "The system provides X" → ✅ "The system SHALL provide X"
45+
- ❌ `- WHEN user does X THEN Y` → ✅ `Given X\nWhen Y\nThen Z`
46+
- ❌ `## New Requirements` → ✅ `## ADDED Requirements`
47+
48+
**Reference**
49+
- See `/rulebook/RULEBOOK.md` for complete format requirements
50+
- Use Context7 MCP to get official OpenSpec format documentation
51+
- Use `rulebook task show <task-id>` to view task details
52+
<!-- RULEBOOK:END -->
53+

0 commit comments

Comments
 (0)