skillstore-cli 1.0.0

package/data/shared/framework/hooks/telegram-notify.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+
+# Telegram Notification Hook (Stop/SubagentStop)
+#
+# Sends Markdown notifications to Telegram when sessions complete.
+# Requires: TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID in environment or .claude/.env
+#
+# Non-blocking: always exits 0.
+
+set -e
+
+# Load environment
+load_env() {
+  local env_files=(
+    "$CLAUDE_PROJECT_DIR/.claude/hooks/.env"
+    "$CLAUDE_PROJECT_DIR/.claude/.env"
+  )
+  for f in "${env_files[@]}"; do
+    if [ -f "$f" ]; then
+      set -a
+      source "$f"
+      set +a
+    fi
+  done
+}
+
+load_env
+
+# Check required vars
+if [ -z "$TELEGRAM_BOT_TOKEN" ] || [ -z "$TELEGRAM_CHAT_ID" ]; then
+  exit 0
+fi
+
+# Read stdin
+INPUT=$(cat /dev/stdin)
+
+# Parse event data
+EVENT_TYPE=$(echo "$INPUT" | node -e "
+  const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+  console.log(d.event || 'unknown');
+" 2>/dev/null || echo "unknown")
+
+TIMESTAMP=$(TZ='Asia/Ho_Chi_Minh' date '+%Y-%m-%d %H:%M:%S')
+
+# Build message
+case "$EVENT_TYPE" in
+  "Stop")
+    EMOJI="✅"
+    TITLE="Session Completed"
+    ;;
+  "SubagentStop")
+    EMOJI="🔵"
+    TITLE="Agent Completed"
+    ;;
+  *)
+    EMOJI="📌"
+    TITLE="Event: $EVENT_TYPE"
+    ;;
+esac
+
+MESSAGE="$EMOJI *$TITLE*
+
+⏰ *Time:* $TIMESTAMP
+📍 *Event:* $EVENT_TYPE
+
+_SkillStore DevFlow_"
+
+# Send Telegram message
+curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"chat_id\": \"${TELEGRAM_CHAT_ID}\",
+    \"text\": \"${MESSAGE}\",
+    \"parse_mode\": \"Markdown\"
+  }" > /dev/null 2>&1 || true
+
+exit 0

package/data/shared/framework/protocols/error-recovery.md

@@ -0,0 +1,80 @@
+# Error Recovery Protocol
+
+All agents and workflows MUST follow this protocol when encountering errors.
+
+---
+
+## Core Principles
+
+1. **No infinite loops** — There must be a clear retry limit
+2. **Analyze before retrying** — Understand WHY it failed before trying again
+3. **Escalate when needed** — Know when to stop and ask the user
+4. **Save progress** — Do not lose work that has already been completed
+
+## Retry Decision Tree
+
+```
+Error occurred
+  │
+  ├─ Build error?
+  │   → Fix immediately
+  │   → Rebuild
+  │   → If same error 3 times → escalate to user
+  │
+  ├─ Test failure?
+  │   ├─ Attempt 1: Fix code based on test output
+  │   ├─ Attempt 2: Check if test itself is wrong
+  │   ├─ Attempt 3: Check if requirement is unclear
+  │   └─ After 3: STOP → report with all 3 analyses
+  │
+  ├─ Agent timeout?
+  │   → Save partial results
+  │   → Report what's done vs. remaining
+  │   → User decides next step
+  │
+  ├─ External dependency fail?
+  │   → Wait 30s, retry once
+  │   → If still fails → report, suggest manual
+  │
+  └─ Unknown error?
+      → Log full error context
+      → DO NOT retry blindly
+      → Report to user with error details
+```
+
+## Recovery Report Format
+
+When escalating to user, use this format:
+
+```markdown
+## Error Report
+
+**Task**: [what was being done]
+**Error**: [what went wrong]
+**Attempts**: [number of retries]
+
+### Analysis
+- Attempt 1: [approach → result]
+- Attempt 2: [approach → result]
+- Attempt 3: [approach → result]
+
+### Diagnostic
+- [Relevant logs/output]
+- [Root cause hypothesis]
+
+### Recommended Next Steps
+1. [Specific action user can take]
+2. [Alternative approach]
+```
+
+## Red Flags — STOP immediately
+
+If you recognize any of the following patterns, STOP and report:
+
+| Red Flag | Meaning |
+|----------|---------|
+| "Quick fix for now, investigate later" | Avoiding root cause |
+| "Just try changing X and see" | Guessing instead of analyzing |
+| "Should work now" (not verified) | Assuming instead of proving |
+| "Let me try one more time" (4th+ attempt) | Looping indefinitely |
+| Same error message appears 3+ times | Root cause has not been fixed |

package/data/shared/framework/protocols/orchestration-protocol.md

@@ -0,0 +1,112 @@
+# Orchestration Protocol
+
+Rules for coordination between agents and workflows. Reference config at `config/skillstore.config.json`.
+
+---
+
+## Sequential Execution
+
+Steps with dependencies MUST run sequentially:
+
+```
+Plan → Implement    (implement needs plan output)
+Implement → Test    (test needs code)
+Test → Review       (review needs test results)
+Review → Fix → Test (loop until pass or max retries)
+```
+
+## Parallel Execution
+
+INDEPENDENT steps can run in parallel via `run_in_background`:
+
+```
+Research Agent 1 + Research Agent 2    (different topics)
+Docs update + Notification             (no shared state)
+Unit tests + Lint check                (independent tools)
+```
+
+**Parallel rules**:
+- Each agent declares files it will modify in the task description
+- If 2 agents modify the same file → run sequentially, NOT in parallel
+- Agents MUST NOT edit files outside their declared scope
+
+## File Conflict Prevention
+
+```
+Agent A: "I will modify src/auth.ts, src/auth.test.ts"
+Agent B: "I will modify src/api.ts, src/api.test.ts"
+→ Parallel OK (no overlap)
+
+Agent A: "I will modify src/config.ts"
+Agent B: "I will modify src/config.ts"
+→ Sequential ONLY (same file)
+```
+
+## Retry Policy
+
+Reference `config.thresholds.maxRetries` (default: 3).
+
+```
+Attempt 1: Execute task normally
+  → Fail: Analyze failure, adjust approach
+Attempt 2: Execute with adjusted approach
+  → Fail: Check if the problem is in the task itself (wrong test, wrong requirement)
+Attempt 3: Execute with alternative approach
+  → Fail: STOP. Report to user with:
+    - What was attempted (3 approaches)
+    - What failed each time
+    - Diagnostic information
+    - Suggested manual steps
+```
+
+**Never**: retry a 4th+ time without new input from the user.
+
+## Timeout Handling
+
+Reference `config.thresholds.agentTimeoutMs` (default: 180000ms = 3 min).
+
+```
+Agent start → [working...] → timeout reached
+  1. Save partial results to task output
+  2. Report: "Timed out after {N}ms. Partial results: {summary}"
+  3. User decides: retry with more time, skip, or manual intervention
+```
+
+## Agent Handoff
+
+When agent A hands off work to agent B:
+
+```markdown
+## Handoff: [Agent A] → [Agent B]
+
+### Completed
+- [List of completed items]
+
+### Context
+- [Key decisions made]
+- [Files modified: list]
+
+### Remaining
+- [What B needs to do]
+
+### Blockers (if any)
+- [Issues B should be aware of]
+```
+
+## Checkpoint Protocol
+
+After each major subtask, the agent MUST:
+1. Update task status (if using TaskCreate/TaskUpdate)
+2. Write a summary: what was done, what remains
+3. If interrupted → the next agent reads the checkpoint to resume
+
+## Escalation Matrix
+
+| Failure | Retry? | Escalation |
+|---------|--------|------------|
+| Build error | Fix immediately, no retry limit | Report if > 3 attempts |
+| Test failure | Max 3 retries | Report with diagnostic |
+| Agent timeout | 1 retry with 2x timeout | Report partial results |
+| File conflict | No retry | Stop, ask user |
+| Unclear requirement | No retry | Stop, ask user |
+| External service down | 1 retry after 30s | Report, suggest manual |

package/data/shared/framework/quality/review-protocol.md

@@ -0,0 +1,76 @@
+# Review Protocol
+
+Code review guide — technical rigor, not performative agreement.
+
+---
+
+## Principles
+
+1. **Technical correctness > social comfort** — If the code is wrong, say so directly
+2. **Verify before agreeing** — Do not accept without checking
+3. **Constructive feedback** — Point out the issue AND suggest a fix
+4. **Scope-aware** — Review according to strictness level, do not over-review
+
+## Review Checklist (by strictness)
+
+### Balanced (default)
+
+**Functionality**
+- Is the logic correct according to requirements?
+- Edge cases: null, empty, boundary values handled?
+- Error handling: exceptions caught at the appropriate level?
+
+**Readability**
+- Is the code self-explanatory? Is naming clear?
+- Is there complex logic that needs an explanatory comment?
+- Consistent with existing codebase conventions?
+
+**Security**
+- No hardcoded secrets/credentials
+- User input validated before processing
+- SQL/command injection prevention (if applicable)
+
+### Strict (in addition to balanced)
+
+**Performance**
+- Unnecessary database queries? N+1?
+- Large data processing has pagination/streaming?
+- Caching opportunities?
+
+**Type Safety**
+- No `any` types (TypeScript)
+- Proper error types (no generic `Error`)
+- Interface/type definitions complete
+
+**Testing**
+- Does new code have corresponding tests?
+- Is test coverage adequate for the new logic?
+- Edge cases tested?
+
+## Review Output Format
+
+```markdown
+## Code Review
+
+### Critical (MUST fix)
+- [File:line] [Issue description] → [Suggested fix]
+
+### Recommended (SHOULD fix)
+- [File:line] [Issue description] → [Suggested fix]
+
+### Observations (FYI)
+- [Notes, patterns, or minor suggestions]
+
+### Verdict
+- [ ] Approved
+- [ ] Approved with minor changes
+- [ ] Changes requested (fix critical issues)
+```
+
+## Anti-Patterns — DO NOT do
+
+- DO NOT give performative agreement: "Great code!" without actually reviewing
+- DO NOT nitpick formatting when there are logic bugs
+- DO NOT suggest adding features outside the scope
+- DO NOT re-architect code that is working well
+- DO NOT block for style preferences (unless it violates team conventions)

package/data/shared/framework/quality/verification-protocol.md

@@ -0,0 +1,66 @@
+# Verification Protocol
+
+Completion verification process — DO NOT claim "done" without evidence.
+
+---
+
+## Golden Rule
+
+**Evidence before assertions.** Run verification commands, confirm output, THEN claim completion.
+
+## Verification Checklist
+
+### Minimum (all strictness levels)
+
+- [ ] Build pass: run build command, verify zero errors
+- [ ] Tests pass: run test command, verify all green
+- [ ] No regression: existing functionality still works
+
+### Balanced (config.strictness = "balanced")
+
+All minimum checks, plus:
+- [ ] Code review: check logic, readability, consistency
+- [ ] Security basics: no hardcoded secrets, input validation at boundaries
+- [ ] Requirements coverage: all acceptance criteria have been addressed
+
+### Strict (config.strictness = "strict")
+
+All balanced checks, plus:
+- [ ] Performance check: no obvious N+1 queries, unnecessary re-renders, etc.
+- [ ] Type safety: no `any` types, proper error types
+- [ ] Security audit: OWASP top 10 check for new code
+- [ ] Edge cases: boundary values, empty states, error states handled
+
+## Self-Review Process
+
+Before claiming done:
+
+1. **Re-read requirements** — Compare output with the original request
+2. **Run verification commands** — Build, test, lint
+3. **Check diff** — Review all of your own changes
+4. **Ask yourself**:
+   - "If this were someone else's code, would I approve this PR?"
+   - "Are there any edge cases I haven't handled?"
+   - "Is there anything hardcoded that should be configurable?"
+
+## Completion Report Format
+
+When claiming done, provide:
+
+```markdown
+## Completion Report
+
+### What was done
+- [Summary of changes]
+
+### Verification Evidence
+- Build: [pass/fail + output snippet]
+- Tests: [pass/fail + count]
+- Other: [relevant checks]
+
+### Files Changed
+- [List of files with brief description]
+
+### Known Limitations
+- [Anything not covered, if applicable]
+```

package/data/shared/framework/rules/development-rules.md

@@ -0,0 +1,75 @@
+# Development Rules
+
+Single source of truth — all agents and workflows reference this file. DO NOT duplicate rules elsewhere.
+
+---
+
+## Critical Rules (2 rules — no exceptions)
+
+1. **NO completion claims without verification evidence.** Before saying "done", there must be actual output: build pass, test pass, or user confirmation.
+
+2. **NO fixes without root cause investigation.** Before fixing, you must understand WHY the error occurred. "Try replacing X and see" is not acceptable.
+
+---
+
+## Standard Rules (adjustable via config.strictness)
+
+### File Organization
+- File size: reference `config.thresholds.maxFileLines` (default 200 LOC)
+- Naming: kebab-case for files, self-documenting names to help LLM tools (Grep/Glob) find quickly
+- Each file should have single responsibility — if a file has > 5 functions/exports, consider splitting
+- DO NOT create new files when you can edit existing ones (avoid file bloat)
+- Use composition over deep inheritance
+
+### Code Quality
+- No hardcoded secrets, credentials, or API keys in code
+- Input validation at system boundaries (user input, external APIs)
+- Error handling at system boundaries — do not over-handle internal code
+- Clean, readable code — code should be self-explanatory, comments only for complex logic
+- Consistent with existing conventions in the codebase
+
+### Workflow
+- Retry limit: reference `config.thresholds.maxRetries` (default 3)
+- After max retries: STOP, report failure, suggest manual steps
+- Agent timeout: reference `config.thresholds.agentTimeoutMs` (default 3 min)
+- Each agent declares files it will modify — do not edit files outside scope
+
+### Testing
+- Build must pass before claiming done
+- Tests must pass — do not ignore failing tests
+- Do not use fake data, mocks, or tricks just to pass tests
+- Flaky test: investigate root cause, do not retry indefinitely
+
+### Code Review (depends on strictness level)
+- **strict**: Full review + security audit + performance check + type safety
+- **balanced**: Review + security basics + obvious performance issues
+- **relaxed**: Build + test pass, review only when there are red flags
+
+### Git
+- Commit messages: English, describe the change, < config.commitMessageMaxChars chars
+- Run build before committing
+- Run tests before pushing
+- Do not commit files containing secrets (.env, credentials, API keys)
+- Do not commit generated files (dist/, build/, coverage/)
+- Clean, professional commit messages — do not reference AI
+
+### Pre-commit Checklist
+1. `build` pass — no syntax/type errors
+2. `test` pass — no failing tests
+3. `lint` pass — no critical violations (if a linter exists)
+4. Review diff — only commit changes related to the task
+5. No secrets — grep for passwords, tokens, keys
+
+---
+
+## Guidelines (suggestions, not enforced)
+
+- Prefer composition over inheritance
+- YAGNI — only build what is needed right now
+- KISS — the simplest solution that works
+- DRY — but 3 identical lines are better than 1 premature abstraction
+- Document non-obvious decisions, do not comment obvious code
+- Prefer editing existing files over creating new ones
+- When unsure: research first, plan second, implement last
+- Agents should use `sequential-thinking` for complex analysis
+- When needing latest docs/APIs: research before assuming

package/data/shared/framework/skills/backend-development/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: backend-development
+description: API design, server architecture, authentication, error handling, and backend performance optimization
+---
+
+# Backend Development
+
+## Triggers
+
+Activate this skill when:
+- Designing or building REST/GraphQL APIs
+- Planning server architecture or microservice boundaries
+- Implementing authentication and authorization
+- Setting up error handling and validation
+- Optimizing database queries or API response times
+- Adding logging, monitoring, or observability
+- Designing gRPC services or protobuf schemas
+- Implementing webhooks (sending or receiving)
+- Applying event sourcing, CQRS, or saga patterns
+- Setting up distributed tracing or circuit breakers
+- Configuring health checks, alerting, or resilience patterns
+- Working with message queues (RabbitMQ, Kafka)
+
+## Process
+
+### 1. API Design
+- Define resources and their relationships
+- Map operations to HTTP methods and endpoints
+- Design request/response schemas with TypeScript or JSON Schema
+- Plan pagination, filtering, and sorting strategies
+- Document with OpenAPI/Swagger from the start
+
+### 2. Implementation
+- Set up layered architecture (controller → service → repository)
+- Implement input validation at the controller layer
+- Write business logic in the service layer (no HTTP concepts)
+- Use repository pattern for data access abstraction
+- Apply dependency injection for testability
+
+### 3. Error Handling
+- Use consistent error response format (RFC 7807 Problem Details)
+- Categorize errors: client (4xx) vs. server (5xx)
+- Never expose internal details (stack traces, SQL) in production
+- Log errors with correlation IDs for tracing
+- Implement global error handler middleware
+
+### 4. Security
+- Validate and sanitize all inputs (allowlist, not blocklist)
+- Implement authentication (JWT, OAuth2, session) based on requirements
+- Apply authorization at route and resource level
+- Use parameterized queries (never string concatenation for SQL)
+- Set security headers (CORS, CSP, HSTS, X-Frame-Options)
+- Rate limit public endpoints
+
+### 5. Testing
+- Unit test service layer logic with mocked repositories
+- Integration test API endpoints with test database
+- Contract tests for inter-service communication
+- Load test critical endpoints with k6 or Artillery
+
+### 6. Documentation
+- Generate OpenAPI spec from code annotations or schema-first
+- Include request/response examples for every endpoint
+- Document error codes and their meanings
+- Provide authentication setup instructions
+
+## References
+
+- [API Design Guide](references/api-design-guide.md) — REST principles, versioning, error formats, auth patterns
+- [Architecture Patterns](references/architecture-patterns.md) — layered architecture, middleware, DI, caching, logging
+- [Advanced Patterns](references/advanced-patterns.md) — gRPC, webhooks, event sourcing, CQRS, sagas, message queues
+- [Observability & Resilience](references/observability-resilience.md) — circuit breakers, tracing, health checks, logging pipelines, alerting
+- [Troubleshooting](references/troubleshooting.md) — connection pool exhaustion, memory leaks, 502/504 tracing, deadlocks, JWT issues, OOM kills
+
+## Assets
+
+- [Sample Output](assets/sample-output.md) — example API design for a Task Management service