Skip to content

Commit 4d2e9ca

Browse files
bayologicalbayological
committed
chore: init spec kit
1 parent c8a9741 commit 4d2e9ca

File tree

11 files changed

+2106
-0
lines changed

11 files changed

+2106
-0
lines changed

‎.specify/memory/constitution.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
<!--
2+
Sync Impact Report:
3+
- Version change: INITIAL → 1.0.0
4+
- New principles added:
5+
1. Type Safety & Code Quality
6+
2. Provider Agnostic Architecture
7+
3. Comprehensive Testing
8+
4. Performance & Reliability
9+
5. Developer Experience & Documentation
10+
6. Blockchain Best Practices
11+
- New sections added:
12+
- Core Principles (6 principles)
13+
- Quality Standards
14+
- Development Workflow
15+
- Governance
16+
- Templates updated:
17+
✅ plan-template.md - Added Constitution Check section with all 6 principles
18+
✅ spec-template.md - Added Non-Functional Requirements section referencing constitution
19+
✅ tasks-template.md - Updated to require tests per constitution, aligned file paths with TypeScript, added constitution compliance to Polish phase
20+
- No command files to update (none exist)
21+
- Follow-up TODOs: None
22+
-->
23+
24+
# Mento SDK Constitution
25+
26+
## Core Principles
27+
28+
### I. Type Safety & Code Quality
29+
30+
The Mento SDK MUST maintain the highest standards of type safety and code quality to ensure reliability in blockchain interactions.
31+
32+
**Non-negotiable rules:**
33+
- TypeScript strict mode MUST be enabled for all source code
34+
- All exported functions, classes, and methods MUST have explicit type annotations
35+
- No `any` types permitted in public APIs (internal use requires documented justification)
36+
- ESLint and Prettier MUST pass with zero warnings on all code
37+
- All code MUST follow the established architectural patterns (adapters, services, types)
38+
- Path aliases MUST be used consistently (`@adapters/*`, `@services/*`, `@types/*`, etc.)
39+
40+
**Rationale**: Blockchain SDKs handle financial transactions and asset management. Type errors can lead to loss of funds. Strict typing catches errors at compile time, provides superior IDE support, and creates self-documenting code that users can trust.
41+
42+
### II. Provider Agnostic Architecture
43+
44+
The SDK MUST remain completely agnostic to the underlying provider implementation, supporting multiple provider ecosystems equally.
45+
46+
**Non-negotiable rules:**
47+
- All blockchain interactions MUST go through the `ProviderAdapter` interface
48+
- Direct provider-specific calls MUST NOT appear in services or business logic
49+
- New provider support MUST be addable by implementing `ProviderAdapter` only
50+
- Adapters MUST handle provider-specific conversions (ABI formats, address formats, etc.)
51+
- Each supported provider (Ethers v5, Ethers v6, Viem) MUST have equal feature parity
52+
- Provider detection and initialization MUST be automatic and type-safe
53+
54+
**Rationale**: The Ethereum/blockchain ecosystem has multiple competing provider libraries. Users should be able to integrate Mento SDK into existing projects without forcing a provider change. This adapter pattern ensures maintainability and allows the SDK to evolve independently of provider library changes.
55+
56+
### III. Comprehensive Testing
57+
58+
Testing MUST be comprehensive, covering all critical paths, provider integrations, and blockchain interactions.
59+
60+
**Non-negotiable rules:**
61+
- All services MUST have unit tests covering core business logic
62+
- Each provider adapter MUST have integration tests verifying blockchain interactions
63+
- Shared test suites MUST be used to ensure consistent behavior across providers
64+
- Code coverage MUST be tracked and maintained above 80% for services
65+
- Tests MUST NOT be skipped without documented justification in PR description
66+
- Integration tests MUST use real blockchain data (mainnet fork or testnet)
67+
- Breaking changes MUST include test updates demonstrating the change
68+
69+
**Test organization:**
70+
- `tests/unit/` - Fast, isolated tests for pure functions and business logic
71+
- `tests/integration/` - Provider-specific tests against real blockchain state
72+
- `tests/integration/shared/` - Reusable test suites ensuring provider parity
73+
74+
**Rationale**: Blockchain SDKs interact with immutable smart contracts and handle real assets. Comprehensive testing is the only way to ensure reliability. Shared test suites prevent provider-specific bugs and ensure users get consistent behavior regardless of their provider choice.
75+
76+
### IV. Performance & Reliability
77+
78+
The SDK MUST be performant and reliable, minimizing unnecessary blockchain calls and handling errors gracefully.
79+
80+
**Non-negotiable rules:**
81+
- Blockchain calls MUST be batched when possible to reduce RPC load
82+
- Retry logic with exponential backoff MUST be implemented for transient failures
83+
- All async operations MUST have proper error handling with meaningful error messages
84+
- No synchronous blocking operations permitted in async code paths
85+
- Network timeouts MUST be configurable or have sensible defaults
86+
- Contract addresses and ABIs MUST be cached and statically defined
87+
- Large data operations MUST be performed iteratively to avoid memory issues
88+
89+
**Performance targets:**
90+
- SDK initialization: < 100ms (excluding network calls)
91+
- Single contract read: < 500ms on mainnet
92+
- Batch operations: Proportional to item count, no O(n²) operations
93+
94+
**Rationale**: Users often integrate SDKs into time-sensitive applications (trading bots, dashboards, DeFi protocols). Slow or unreliable SDKs lead to poor user experience or lost opportunities. Blockchain RPC nodes have rate limits, so efficient call patterns are essential.
95+
96+
### V. Developer Experience & Documentation
97+
98+
The SDK MUST provide an exceptional developer experience through clear APIs, comprehensive documentation, and helpful error messages.
99+
100+
**Non-negotiable rules:**
101+
- All public APIs MUST have JSDoc comments with usage examples
102+
- README MUST include quick start guides for each supported provider
103+
- Breaking changes MUST be clearly documented with migration guides
104+
- Error messages MUST be actionable (tell users what went wrong AND how to fix it)
105+
- TypeScript types MUST be exported and available to SDK consumers
106+
- Examples MUST be tested and kept up-to-date with API changes
107+
108+
**Documentation requirements:**
109+
- Each service MUST document its purpose and primary use cases
110+
- Complex functions MUST include `@dev` comments with implementation notes
111+
- Public types MUST have property-level documentation
112+
- README MUST be updated when adding/removing features
113+
114+
**Rationale**: SDK adoption depends on how quickly developers can get started and how easily they can debug issues. Good documentation and developer experience reduces support burden and increases user satisfaction.
115+
116+
### VI. Blockchain Best Practices
117+
118+
The SDK MUST follow blockchain and Web3 best practices to ensure security and compatibility.
119+
120+
**Non-negotiable rules:**
121+
- All contract addresses MUST be checksummed and validated
122+
- Chain IDs MUST be verified to prevent cross-chain replay attacks
123+
- ABIs MUST match deployed contracts (verified against on-chain bytecode when possible)
124+
- Gas estimation MUST be available for state-changing operations
125+
- Event subscriptions MUST handle reorganizations gracefully
126+
- Numeric values MUST use BigNumber/BigInt to prevent precision loss
127+
- Contract calls MUST specify exact function signatures to prevent ambiguity
128+
129+
**Security considerations:**
130+
- Never trust user input - validate all addresses, amounts, and parameters
131+
- Never expose private keys or sensitive data in logs or errors
132+
- Follow principle of least privilege for contract interactions
133+
134+
**Rationale**: Blockchain development has unique security considerations. Incorrect address formats, chain ID mismatches, or floating-point arithmetic can lead to loss of funds. Following established best practices prevents common vulnerabilities.
135+
136+
## Quality Standards
137+
138+
### Code Organization
139+
- One class per file, filename matches class name
140+
- Related functionality grouped in services
141+
- Shared types centralized in `@types/*`
142+
- ABIs separated by contract in `@abis/*`
143+
- Constants organized by concern (addresses, chain IDs, etc.)
144+
145+
### Dependency Management
146+
- Peer dependencies for provider libraries (optional to allow user choice)
147+
- Minimal production dependencies (current: only BigNumber.js)
148+
- Dev dependencies pinned to prevent build inconsistencies
149+
- Node.js >= 18 and pnpm >= 9 required
150+
151+
### Version Management
152+
- Semantic versioning (MAJOR.MINOR.PATCH)
153+
- MAJOR: Breaking API changes, provider support changes
154+
- MINOR: New features, new chains, backward-compatible additions
155+
- PATCH: Bug fixes, documentation, dependency updates
156+
157+
## Development Workflow
158+
159+
### Pull Request Requirements
160+
- All tests MUST pass (unit + integration)
161+
- ESLint and Prettier checks MUST pass
162+
- Code coverage MUST not decrease (exceptions require justification)
163+
- At least one approval from core maintainer
164+
- Meaningful commit messages following conventional commits
165+
166+
### Testing Workflow
167+
1. Write tests first for new features (test-driven development encouraged)
168+
2. Ensure tests fail before implementation
169+
3. Implement feature
170+
4. Verify all tests pass
171+
5. Check coverage report
172+
173+
### Review Checklist
174+
- [ ] TypeScript strict mode compliance
175+
- [ ] All provider adapters maintain feature parity
176+
- [ ] JSDoc comments on public APIs
177+
- [ ] Error messages are actionable
178+
- [ ] Tests cover new functionality
179+
- [ ] README updated if adding/changing public API
180+
- [ ] No hardcoded values (use constants)
181+
- [ ] Async operations have error handling
182+
183+
## Governance
184+
185+
### Constitution Authority
186+
This constitution supersedes all other development practices, guidelines, or preferences. When conflicts arise between this constitution and other documentation, the constitution takes precedence.
187+
188+
### Amendment Process
189+
1. Proposed changes MUST be documented with rationale
190+
2. Changes MUST have approval from at least 2 core maintainers
191+
3. Version MUST be bumped according to change significance:
192+
- MAJOR: Removing/changing core principles
193+
- MINOR: Adding new principles or sections
194+
- PATCH: Clarifications, typos, non-semantic changes
195+
4. All dependent templates MUST be updated for consistency
196+
5. A sync impact report MUST be included with the amendment
197+
198+
### Compliance Review
199+
- All PRs MUST verify alignment with these principles
200+
- New complexity or architectural patterns MUST be justified against simplicity
201+
- Violations require documented rationale and core maintainer approval
202+
- Constitution review recommended quarterly or after major features
203+
204+
### Conflict Resolution
205+
When principles conflict in practice:
206+
1. Security and correctness take precedence over performance
207+
2. User experience takes precedence over implementation simplicity
208+
3. Type safety takes precedence over brevity
209+
4. Consult core maintainers for guidance on edge cases
210+
211+
**Version**: 1.0.0 | **Ratified**: 2025-11-03 | **Last Amended**: 2025-11-03

‎.specify/scripts/bash/check-prerequisites.sh‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
#!/usr/bin/env bash
2+
3+
# Consolidated prerequisite checking script
4+
#
5+
# This script provides unified prerequisite checking for Spec-Driven Development workflow.
6+
# It replaces the functionality previously spread across multiple scripts.
7+
#
8+
# Usage: ./check-prerequisites.sh [OPTIONS]
9+
#
10+
# OPTIONS:
11+
# --json Output in JSON format
12+
# --require-tasks Require tasks.md to exist (for implementation phase)
13+
# --include-tasks Include tasks.md in AVAILABLE_DOCS list
14+
# --paths-only Only output path variables (no validation)
15+
# --help, -h Show help message
16+
#
17+
# OUTPUTS:
18+
# JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
19+
# Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
20+
# Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
21+
22+
set -e
23+
24+
# Parse command line arguments
25+
JSON_MODE=false
26+
REQUIRE_TASKS=false
27+
INCLUDE_TASKS=false
28+
PATHS_ONLY=false
29+
30+
for arg in "$@"; do
31+
case "$arg" in
32+
--json)
33+
JSON_MODE=true
34+
;;
35+
--require-tasks)
36+
REQUIRE_TASKS=true
37+
;;
38+
--include-tasks)
39+
INCLUDE_TASKS=true
40+
;;
41+
--paths-only)
42+
PATHS_ONLY=true
43+
;;
44+
--help|-h)
45+
cat << 'EOF'
46+
Usage: check-prerequisites.sh [OPTIONS]
47+
48+
Consolidated prerequisite checking for Spec-Driven Development workflow.
49+
50+
OPTIONS:
51+
--json Output in JSON format
52+
--require-tasks Require tasks.md to exist (for implementation phase)
53+
--include-tasks Include tasks.md in AVAILABLE_DOCS list
54+
--paths-only Only output path variables (no prerequisite validation)
55+
--help, -h Show this help message
56+
57+
EXAMPLES:
58+
# Check task prerequisites (plan.md required)
59+
./check-prerequisites.sh --json
60+
61+
# Check implementation prerequisites (plan.md + tasks.md required)
62+
./check-prerequisites.sh --json --require-tasks --include-tasks
63+
64+
# Get feature paths only (no validation)
65+
./check-prerequisites.sh --paths-only
66+
67+
EOF
68+
exit 0
69+
;;
70+
*)
71+
echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
72+
exit 1
73+
;;
74+
esac
75+
done
76+
77+
# Source common functions
78+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
79+
source "$SCRIPT_DIR/common.sh"
80+
81+
# Get feature paths and validate branch
82+
eval $(get_feature_paths)
83+
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
84+
85+
# If paths-only mode, output paths and exit (support JSON + paths-only combined)
86+
if $PATHS_ONLY; then
87+
if $JSON_MODE; then
88+
# Minimal JSON paths payload (no validation performed)
89+
printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
90+
"$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
91+
else
92+
echo "REPO_ROOT: $REPO_ROOT"
93+
echo "BRANCH: $CURRENT_BRANCH"
94+
echo "FEATURE_DIR: $FEATURE_DIR"
95+
echo "FEATURE_SPEC: $FEATURE_SPEC"
96+
echo "IMPL_PLAN: $IMPL_PLAN"
97+
echo "TASKS: $TASKS"
98+
fi
99+
exit 0
100+
fi
101+
102+
# Validate required directories and files
103+
if [[ ! -d "$FEATURE_DIR" ]]; then
104+
echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
105+
echo "Run /speckit.specify first to create the feature structure." >&2
106+
exit 1
107+
fi
108+
109+
if [[ ! -f "$IMPL_PLAN" ]]; then
110+
echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
111+
echo "Run /speckit.plan first to create the implementation plan." >&2
112+
exit 1
113+
fi
114+
115+
# Check for tasks.md if required
116+
if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
117+
echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
118+
echo "Run /speckit.tasks first to create the task list." >&2
119+
exit 1
120+
fi
121+
122+
# Build list of available documents
123+
docs=()
124+
125+
# Always check these optional docs
126+
[[ -f "$RESEARCH" ]] && docs+=("research.md")
127+
[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
128+
129+
# Check contracts directory (only if it exists and has files)
130+
if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
131+
docs+=("contracts/")
132+
fi
133+
134+
[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
135+
136+
# Include tasks.md if requested and it exists
137+
if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
138+
docs+=("tasks.md")
139+
fi
140+
141+
# Output results
142+
if $JSON_MODE; then
143+
# Build JSON array of documents
144+
if [[ ${#docs[@]} -eq 0 ]]; then
145+
json_docs="[]"
146+
else
147+
json_docs=$(printf '"%s",' "${docs[@]}")
148+
json_docs="[${json_docs%,}]"
149+
fi
150+
151+
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
152+
else
153+
# Text output
154+
echo "FEATURE_DIR:$FEATURE_DIR"
155+
echo "AVAILABLE_DOCS:"
156+
157+
# Show status of each potential document
158+
check_file "$RESEARCH" "research.md"
159+
check_file "$DATA_MODEL" "data-model.md"
160+
check_dir "$CONTRACTS_DIR" "contracts/"
161+
check_file "$QUICKSTART" "quickstart.md"
162+
163+
if $INCLUDE_TASKS; then
164+
check_file "$TASKS" "tasks.md"
165+
fi
166+
fi

0 commit comments

Comments
 (0)