Skip to content

Commit c70522a

Browse files
teratronteratron
committed
feat: Add new specifications, tests and agent notes
- Add specification files for feature analysis and enhancement. - Add notes for different agents (CLAUDE, GEMINI, QWEN). - Add contract and integration tests for template creation and validation. - Remove old test file test_expert.py.
1 parent 5636f33 commit c70522a

14 files changed

Lines changed: 819 additions & 0 deletions

File tree

‎.specify/specs/feature/analysis-and-enhancement/contracts/template-create.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Template Creation Contract
2+
3+
## Endpoint
4+
POST /template/create
5+
6+
## Description
7+
Creates a new trading strategy template file for a user.
8+
9+
## Request
10+
```json
11+
{
12+
"strategy_name": "string",
13+
"output_directory": "string"
14+
}
15+
```
16+
17+
## Response
18+
```json
19+
{
20+
"status": "success|error",
21+
"message": "string",
22+
"file_path": "string"
23+
}
24+
```
25+
26+
## Error Responses
27+
- 400: Invalid request parameters
28+
- 500: Internal server error

‎.specify/specs/feature/analysis-and-enhancement/data-model.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Data Model: MetaExpert Library Template Enhancement
2+
3+
## Entities
4+
5+
### TemplateFile
6+
Represents the template.py file that serves as the starting point for all trading strategies.
7+
8+
**Attributes:**
9+
- path: string - File path where the template is located
10+
- content: string - The content of the template file
11+
- version: string - Version of the template
12+
- last_modified: datetime - When the template was last modified
13+
14+
**Relationships:**
15+
- None (standalone entity)
16+
17+
### ConfigurationParameter
18+
Represents a configuration parameter in the template.
19+
20+
**Attributes:**
21+
- name: string - Name of the parameter
22+
- description: string - Description of what the parameter does
23+
- default_value: string - Default value of the parameter
24+
- category: string - Category/group the parameter belongs to
25+
- required: boolean - Whether the parameter is required
26+
27+
**Relationships:**
28+
- Belongs to TemplateFile (one-to-many)
29+
30+
### EventHandler
31+
Represents an event handler function in the template.
32+
33+
**Attributes:**
34+
- name: string - Name of the event handler function
35+
- description: string - Description of when the handler is called
36+
- parameters: list - List of parameters the handler accepts
37+
- decorator: string - The decorator used to register the handler
38+
39+
**Relationships:**
40+
- Belongs to TemplateFile (one-to-many)
41+
42+
### Exchange
43+
Represents a supported exchange.
44+
45+
**Attributes:**
46+
- name: string - Name of the exchange
47+
- supported_features: list - List of features supported by the exchange
48+
- api_documentation_url: string - URL to the exchange's API documentation
49+
50+
**Relationships:**
51+
- Referenced in TemplateFile configuration

‎.specify/specs/feature/analysis-and-enhancement/plan.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
2+
# Implementation Plan: MetaExpert Library Template Enhancement
3+
4+
**Branch**: `feature/analysis-and-enhancement` | **Date**: 2025-09-20 | **Spec**: [link](spec.md)
5+
**Input**: Feature specification from `/specs/feature/analysis-and-enhancement/spec.md`
6+
7+
## Execution Flow (/plan command scope)
8+
```
9+
1. Load feature spec from Input path
10+
→ If not found: ERROR "No feature spec at {path}"
11+
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
12+
→ Detect Project Type from context (web=frontend+backend, mobile=app+api)
13+
→ Set Structure Decision based on project type
14+
3. Fill the Constitution Check section based on the content of the constitution document.
15+
4. Evaluate Constitution Check section below
16+
→ If violations exist: Document in Complexity Tracking
17+
→ If no justification possible: ERROR "Simplify approach first"
18+
→ Update Progress Tracking: Initial Constitution Check
19+
5. Execute Phase 0 → research.md
20+
→ If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
21+
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
22+
7. Re-evaluate Constitution Check section
23+
→ If new violations: Refactor design, return to Phase 1
24+
→ Update Progress Tracking: Post-Design Constitution Check
25+
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
26+
9. STOP - Ready for /tasks command
27+
```
28+
29+
**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
30+
- Phase 2: /tasks command creates tasks.md
31+
- Phase 3-4: Implementation execution (manual or via tools)
32+
33+
## Summary
34+
This feature focuses on ensuring the template.py file serves as a robust starting point for developers creating trading strategies with the MetaExpert library. The template must preserve all core functionality while allowing for strategy-specific customization.
35+
36+
## Technical Context
37+
**Language/Version**: Python 3.12
38+
**Primary Dependencies**: MetaExpert library, supported exchange APIs
39+
**Storage**: N/A
40+
**Testing**: pytest
41+
**Target Platform**: Cross-platform (Windows, Linux, macOS)
42+
**Project Type**: single (library-based)
43+
**Performance Goals**: N/A
44+
**Constraints**: Template file structure must remain consistent with MetaExpert library requirements. For all tasks related to the MetaExpert project, use only the UV package manager (no pip, requirements.txt, setup.py, or similar). Always activate the virtual environment using .venv/Scripts/activate before executing any UV commands.
45+
**Scale/Scope**: Single template file for all user projects
46+
47+
## Constitution Check
48+
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
49+
50+
Based on the MetaExpert Constitution v1.1.0, the following gates must be checked:
51+
52+
1. Library-First Development: All features must start as standalone libraries that are self-contained, independently testable, and well-documented.
53+
2. CLI Interface Standard: Functionality must be exposed via Command Line Interface with text-based protocols.
54+
3. Test-First Development: Test-Driven Development is mandatory with Red-Green-Refactor cycle enforcement.
55+
4. Integration Testing Coverage: Integration tests are required for new contracts, contract changes, and inter-service communication.
56+
5. Observability & Versioning: Structured logging is required, and versioning follows MAJOR.MINOR.BUILD format.
57+
6. Package Management: Only the UV package manager must be used for all dependency management tasks.
58+
59+
## Project Structure
60+
61+
### Documentation (this feature)
62+
```
63+
specs/feature/analysis-and-enhancement/
64+
├── plan.md # This file (/plan command output)
65+
├── research.md # Phase 0 output (/plan command)
66+
├── data-model.md # Phase 1 output (/plan command)
67+
├── quickstart.md # Phase 1 output (/plan command)
68+
├── contracts/ # Phase 1 output (/plan command)
69+
└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
70+
```
71+
72+
### Source Code (repository root)
73+
```
74+
# Option 1: Single project (DEFAULT)
75+
src/
76+
├── models/
77+
├── services/
78+
├── cli/
79+
└── lib/
80+
81+
tests/
82+
├── contract/
83+
├── integration/
84+
└── unit/
85+
```
86+
87+
**Structure Decision**: DEFAULT to Option 1 as this is a single library project
88+
89+
## Phase 0: Outline & Research
90+
1. **Extract unknowns from Technical Context** above:
91+
- For each NEEDS CLARIFICATION → research task
92+
- For each dependency → best practices task
93+
- For each integration → patterns task
94+
95+
2. **Generate and dispatch research agents**:
96+
```
97+
For each unknown in Technical Context:
98+
Task: "Research {unknown} for {feature context}"
99+
For each technology choice:
100+
Task: "Find best practices for {tech} in {domain}"
101+
```
102+
103+
3. **Consolidate findings** in `research.md` using format:
104+
- Decision: [what was chosen]
105+
- Rationale: [why chosen]
106+
- Alternatives considered: [what else evaluated]
107+
108+
**Output**: research.md with all NEEDS CLARIFICATION resolved
109+
110+
## Phase 1: Design & Contracts
111+
*Prerequisites: research.md complete*
112+
113+
1. **Extract entities from feature spec** → `data-model.md`:
114+
- Entity name, fields, relationships
115+
- Validation rules from requirements
116+
- State transitions if applicable
117+
118+
2. **Generate API contracts** from functional requirements:
119+
- For each user action → endpoint
120+
- Use standard REST/GraphQL patterns
121+
- Output OpenAPI/GraphQL schema to `/contracts/`
122+
123+
3. **Generate contract tests** from contracts:
124+
- One test file per endpoint
125+
- Assert request/response schemas
126+
- Tests must fail (no implementation yet)
127+
128+
4. **Extract test scenarios** from user stories:
129+
- Each story → integration test scenario
130+
- Quickstart test = story validation steps
131+
132+
5. **Update agent file incrementally** (O(1) operation):
133+
- Run `.specify/scripts/powershell/update-agent-context.ps1 -AgentType gemini` for your AI assistant
134+
- If exists: Add only NEW tech from current plan
135+
- Preserve manual additions between markers
136+
- Update recent changes (keep last 3)
137+
- Keep under 150 lines for token efficiency
138+
- Output to repository root
139+
140+
**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
141+
142+
## Phase 2: Task Planning Approach
143+
*This section describes what the /tasks command will do - DO NOT execute during /plan*
144+
145+
**Task Generation Strategy**:
146+
- Load `.specify/templates/tasks-template.md` as base
147+
- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
148+
- Each contract → contract test task [P]
149+
- Each entity → model creation task [P]
150+
- Each user story → integration test task
151+
- Implementation tasks to make tests pass
152+
153+
**Ordering Strategy**:
154+
- TDD order: Tests before implementation
155+
- Dependency order: Models before services before UI
156+
- Mark [P] for parallel execution (independent files)
157+
158+
**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
159+
160+
**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
161+
162+
## Phase 3+: Future Implementation
163+
*These phases are beyond the scope of the /plan command*
164+
165+
**Phase 3**: Task execution (/tasks command creates tasks.md)
166+
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
167+
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
168+
169+
## Complexity Tracking
170+
*Fill ONLY if Constitution Check has violations that must be justified*
171+
172+
| Violation | Why Needed | Simpler Alternative Rejected Because |
173+
|-----------|------------|-------------------------------------|
174+
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
175+
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
176+
177+
178+
## Progress Tracking
179+
*This checklist is updated during execution flow*
180+
181+
**Phase Status**:
182+
- [x] Phase 0: Research complete (/plan command)
183+
- [x] Phase 1: Design complete (/plan command)
184+
- [x] Phase 2: Task planning complete (/plan command - describe approach only)
185+
- [x] Phase 3: Tasks generated (/tasks command)
186+
- [ ] Phase 4: Implementation complete
187+
- [ ] Phase 5: Validation passed
188+
189+
**Gate Status**:
190+
- [x] Initial Constitution Check: PASS
191+
- [x] Post-Design Constitution Check: PASS
192+
- [x] All NEEDS CLARIFICATION resolved
193+
- [x] Complexity deviations documented
194+
195+
---
196+
*Based on Constitution v1.1.0 - See `/memory/constitution.md`*

0 commit comments

Comments
 (0)