speccrew 0.1.0

package/.speccrew/skills/speccrew-knowledge-techs-index/templates/INDEX-TEMPLATE.md

@@ -0,0 +1,243 @@
+# Technology Knowledge Index
+
+<cite>
+**Files Referenced in This Document**
+- [techs-manifest.json](file://{{manifest_path}})
+</cite>
+
+> **Target Audience**: devcrew-designer-*, devcrew-dev-*, devcrew-test-*
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendix](#appendix)
+
+## Introduction
+
+This technology knowledge index serves all platforms in the project, providing platform overview, document navigation, and Agent usage guidelines.
+
+> Generated at: {{generated_at}}
+> Source: {{source_path}}
+> Platforms: {{platform_count}}
+
+## Project Structure
+
+### Platform Overview
+
+Summary table of all platforms:
+
+| Platform | Type | Framework | Language | Documents |
+|----------|------|-----------|----------|-----------|
+{{#each platforms}}
+| [{{name}}]({{platform_id}}/INDEX.md) | {{platform_type}} | {{framework}} {{version}} | {{language}} | [Stack]({{platform_id}}/tech-stack.md), [Arch]({{platform_id}}/architecture.md), [Design]({{platform_id}}/conventions-design.md), [Dev]({{platform_id}}/conventions-dev.md), [Test]({{platform_id}}/conventions-test.md) |
+{{/each}}
+
+### Directory Structure
+
+```
+techs/
+├── INDEX.md                    # This file (root index)
+{{#each platforms}}
+├── {{platform_id}}/
+│   ├── INDEX.md
+│   ├── tech-stack.md
+│   ├── architecture.md
+│   ├── conventions-design.md
+│   ├── conventions-dev.md
+│   ├── conventions-test.md
+│   └── conventions-data.md (optional)
+{{/each}}
+```
+
+**Section Source**
+- [techs-manifest.json](file://{{manifest_path}})
+
+## Core Components
+
+### Technology Stacks
+
+{{#each platforms}}
+- [{{name}} - {{framework}}]({{platform_id}}/tech-stack.md)
+{{/each}}
+
+### Architecture Guidelines
+
+{{#each platforms}}
+- [{{name}}]({{platform_id}}/architecture.md)
+{{/each}}
+
+### Design Conventions
+
+{{#each platforms}}
+- [{{name}}]({{platform_id}}/conventions-design.md)
+{{/each}}
+
+### Development Conventions
+
+{{#each platforms}}
+- [{{name}}]({{platform_id}}/conventions-dev.md)
+{{/each}}
+
+### Testing Conventions
+
+{{#each platforms}}
+- [{{name}}]({{platform_id}}/conventions-test.md)
+{{/each}}
+
+[This section provides navigation, aggregated from platform documents]
+
+## Architecture Overview
+
+### Platform Architecture Map
+
+```mermaid
+graph TB
+Root["Technology Knowledge Index"]
+{{#each platforms}}
+{{platform_id}}["{{name}}"]
+Root --> {{platform_id}}
+{{/each}}
+```
+
+**Diagram Source**
+- [techs-manifest.json](file://{{manifest_path}})
+
+**Section Source**
+- [techs-manifest.json](file://{{manifest_path}})
+
+## Detailed Component Analysis
+
+### Agent-to-Platform Mapping
+
+This section maps dynamically generated Agents to their respective platform documentation.
+
+{{#each platforms}}
+#### {{name}} ({{platform_id}})
+
+| Agent Role | Agent Name | Documentation Path |
+|------------|------------|-------------------|
+| Designer | devcrew-designer-{{platform_id}} | [knowledge/techs/{{platform_id}}/]({{platform_id}}/) |
+| Developer | devcrew-dev-{{platform_id}} | [knowledge/techs/{{platform_id}}/]({{platform_id}}/) |
+| Tester | devcrew-test-{{platform_id}} | [knowledge/techs/{{platform_id}}/]({{platform_id}}/) |
+
+**Key Documents for {{name}} Agents:**
+- Designer: [architecture.md]({{platform_id}}/architecture.md), [conventions-design.md]({{platform_id}}/conventions-design.md)
+- Developer: [conventions-dev.md]({{platform_id}}/conventions-dev.md)
+- Tester: [conventions-test.md]({{platform_id}}/conventions-test.md)
+
+{{/each}}
+
+**Section Source**
+- [techs-manifest.json](file://{{manifest_path}})
+
+## Dependency Analysis
+
+### Cross-Platform Dependencies
+
+{{cross_platform_dependencies}}
+
+```mermaid
+graph LR
+{{#each platforms}}
+{{platform_id}}["{{name}}"]
+{{/each}}
+{{#each platform_relations}}
+{{from}} --> {{to}}
+{{/each}}
+```
+
+**Diagram Source**
+- [techs-manifest.json](file://{{manifest_path}})
+
+**Section Source**
+- [techs-manifest.json](file://{{manifest_path}})
+
+## Performance Considerations
+
+### Platform Performance Characteristics
+
+{{performance_considerations}}
+
+[This section provides general guidance, no specific file reference required]
+
+## Troubleshooting Guide
+
+### Common Issues
+
+{{#each troubleshooting}}
+#### {{issue}}
+
+**Symptoms:**
+{{#each symptoms}}
+- {{this}}
+{{/each}}
+
+**Solutions:**
+{{#each solutions}}
+- {{this}}
+{{/each}}
+
+{{/each}}
+
+**Section Source**
+{{#each troubleshooting_sources}}
+- [{{name}}](file://{{path}}#L{{start}}-L{{end}})
+{{/each}}
+
+## Conclusion
+
+{{conclusion}}
+
+[This section is a summary, no specific file reference required]
+
+## Appendix
+
+### Document Guide
+
+#### INDEX.md (per platform)
+Platform-specific overview and navigation.
+
+#### tech-stack.md
+Framework versions, dependencies, build tools, and configuration files.
+
+#### architecture.md
+Architecture patterns, layering, component organization, and design patterns.
+
+#### conventions-design.md
+Design principles, patterns, and guidelines for detailed design work.
+
+#### conventions-dev.md
+Naming conventions, code style, directory structure, and Git conventions.
+
+#### conventions-test.md
+Testing frameworks, coverage requirements, and testing patterns.
+
+#### conventions-data.md
+Data modeling, ORM usage, and database conventions (if applicable).
+
+### Usage Guide
+
+#### For Designer Agents
+1. Read [architecture.md] for platform architecture patterns
+2. Read [conventions-design.md] for design principles
+3. Reference [tech-stack.md] for technology capabilities
+
+#### For Developer Agents
+1. Read [conventions-dev.md] for coding standards
+2. Read [conventions-test.md] for testing requirements
+3. Reference [architecture.md] when implementation details are unclear
+
+#### For Tester Agents
+1. Read [conventions-test.md] for testing standards
+2. Reference [conventions-design.md] to understand design intent
+
+**Section Source**
+- [techs-manifest.json](file://{{manifest_path}})

package/.speccrew/skills/speccrew-knowledge-techs-init/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: speccrew-knowledge-techs-init
+description: Stage 1 of technology knowledge initialization - Scan source code to detect technology platforms and generate techs-manifest.json. Identifies web, mobile, backend, and desktop platforms by analyzing configuration files and project structure. Used by Worker Agent to kick off the techs pipeline.
+tools: Read, Write, Glob, Grep, SearchCodebase, Skill
+---
+
+# Stage 1: Detect Technology Platforms
+
+Scan project source code to identify all technology platforms, extract configuration metadata, and generate techs-manifest.json for downstream document generation.
+
+## Language Adaptation
+
+**CRITICAL**: Generate all content in the language specified by the `language` parameter.
+
+- `language: "zh"` → Generate all content in 中文
+- `language: "en"` → Generate all content in English
+- Other languages → Use the specified language
+
+**All output content must be in the target language only.**
+
+## Trigger Scenarios
+
+- "Initialize technology knowledge base"
+- "Scan source code for technology platforms"
+- "Detect tech stacks in project"
+- "Generate techs manifest"
+
+## User
+
+Worker Agent (speccrew-task-worker)
+
+## Input
+
+- `source_path`: Source code root directory (default: project root)
+- `output_path`: Output directory for techs-manifest.json (default: `speccrew-workspace/knowledges/base/sync-state/knowledge-techs/`)
+- `language`: Target language for generated content (e.g., "zh", "en") - **REQUIRED**
+
+## Output
+
+- `{{output_path}}/techs-manifest.json` - Technology platform manifest for pipeline orchestration
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Step1[Step 1: Scan for Platform Indicators]
+    Step1 --> Step2[Step 2: Extract Platform Metadata]
+    Step2 --> Step3[Step 3: Generate techs-manifest.json]
+    Step3 --> Step4[Step 4: Report Results]
+    Step4 --> End([End])
+```
+
+### Step 1: Scan for Platform Indicators
+
+1. **Read Configuration**:
+   - Read `speccrew-workspace/docs/configs/platform-mapping.json` - Get standardized platform identifiers and mapping rules
+
+2. **Analyze project structure to detect technology platforms**:
+   - Check for platform-specific files and configurations (see [Platform Detection Reference](#platform-detection-reference))
+
+#### Web Platform Detection
+
+**Indicators:**
+
+| Signal | Platform ID | Framework |
+|--------|-------------|-----------|
+| package.json + react dependency | web-react | React |
+| package.json + vue dependency | web-vue | Vue |
+| package.json + @angular/core | web-angular | Angular |
+| package.json + next | web-nextjs | Next.js |
+| package.json + nuxt | web-nuxt | Nuxt |
+| package.json + svelte | web-svelte | Svelte |
+
+**Configuration Files to Capture:**
+- package.json
+- tsconfig.json
+- vite.config.* / webpack.config.* / next.config.* / nuxt.config.*
+- tailwind.config.* / postcss.config.*
+- .eslintrc.* / .prettierrc.*
+
+#### Mobile Platform Detection
+
+**Indicators:**
+
+| Signal | Platform ID | Framework |
+|--------|-------------|-----------|
+| pubspec.yaml | mobile-flutter | Flutter |
+| package.json + react-native | mobile-react-native | React Native |
+| .xcodeproj / Package.swift | mobile-ios | iOS (Swift) |
+| build.gradle + AndroidManifest.xml | mobile-android | Android (Kotlin/Java) |
+| manifest.json + pages.json (uni-app) | mobile-uniapp | UniApp |
+| project.config.json + app.json | mobile-miniprogram | Mini Program |
+
+**Configuration Files to Capture:**
+- Flutter: pubspec.yaml, analysis_options.yaml
+- React Native: package.json, metro.config.js
+- iOS: Package.swift, Podfile, Info.plist
+- Android: build.gradle, AndroidManifest.xml
+
+#### Backend Platform Detection
+
+**Indicators:**
+
+| Signal | Platform ID | Framework |
+|--------|-------------|-----------|
+| package.json + @nestjs/core | backend-nestjs | NestJS |
+| package.json + express | backend-express | Express |
+| package.json + fastify | backend-fastify | Fastify |
+| pom.xml + spring-boot | backend-spring | Spring Boot |
+| build.gradle + spring-boot | backend-spring | Spring Boot |
+| requirements.txt + django | backend-django | Django |
+| requirements.txt + fastapi | backend-fastapi | FastAPI |
+| go.mod | backend-go | Go |
+| Cargo.toml | backend-rust | Rust (Actix/Rocket) |
+
+**Configuration Files to Capture:**
+- Node.js: package.json, tsconfig.json, nest-cli.json
+- Java: pom.xml, build.gradle, application.yml/properties
+- Python: requirements.txt, pyproject.toml
+- Go: go.mod, go.sum
+- Rust: Cargo.toml
+
+#### Desktop Platform Detection
+
+**Indicators:**
+
+| Signal | Platform ID | Framework |
+|--------|-------------|-----------|
+| package.json + electron | desktop-electron | Electron |
+| tauri.conf.json | desktop-tauri | Tauri |
+| .csproj + WPF references | desktop-wpf | WPF |
+| .csproj + WinForms | desktop-winforms | WinForms |
+| .pro file + Qt | desktop-qt | Qt |
+
+**Configuration Files to Capture:**
+- Electron: package.json, electron-builder.yml
+- Tauri: tauri.conf.json, Cargo.toml
+- WPF/WinForms: .csproj, App.xaml
+- Qt: .pro, CMakeLists.txt
+
+### Step 2: Extract Platform Metadata
+
+For each detected platform, extract:
+
+| Field | Source | Example |
+|-------|--------|---------|
+| platform_id | `{{platform_type}}-{{framework}}` | web-react, backend-nestjs |
+| platform_type | Platform category | web, mobile, backend, desktop |
+| framework | Primary framework | react, nestjs, flutter |
+| language | Primary language | typescript, kotlin, dart |
+| source_path | Relative source directory | src/web, src/server |
+| config_files | List of config file paths | ["package.json", "tsconfig.json"] |
+| convention_files | Lint/format config files | [".eslintrc.js", ".prettierrc"] |
+
+### Step 3: Generate techs-manifest.json
+
+1. **Get Timestamp**:
+   - **CRITICAL**: Use the Skill tool to invoke `speccrew-get-timestamp` (no format parameter needed, uses default)
+   - Store the returned timestamp as `generated_at` value
+
+2. **Create JSON file** with detected platforms:
+
+```json
+{
+  "generated_at": "{{timestamp_from_get_timestamp}}",
+  "source_path": "/project",
+  "language": "zh",
+  "platforms": [
+    {
+      "platform_id": "web-react",
+      "platform_type": "web",
+      "framework": "react",
+      "language": "typescript",
+      "source_path": "src/web",
+      "config_files": [
+        "src/web/package.json",
+        "src/web/tsconfig.json",
+        "src/web/vite.config.ts"
+      ],
+      "convention_files": [
+        "src/web/.eslintrc.js",
+        "src/web/.prettierrc"
+      ]
+    },
+    {
+      "platform_id": "backend-nestjs",
+      "platform_type": "backend",
+      "framework": "nestjs",
+      "language": "typescript",
+      "source_path": "src/server",
+      "config_files": [
+        "src/server/package.json",
+        "src/server/nest-cli.json",
+        "src/server/tsconfig.json"
+      ],
+      "convention_files": [
+        "src/server/.eslintrc.js"
+      ]
+    }
+  ]
+}
+```
+
+### Step 4: Report Results
+
+```
+Stage 1 completed: Technology Platform Detection
+- Platforms Detected: {{platform_count}}
+  - web-react: React 18.2.0, TypeScript 5.3.0
+  - backend-nestjs: NestJS 10.0.0, TypeScript 5.3.0
+- Configuration Files Found: {{config_file_count}}
+- Output: {{output_path}}/techs-manifest.json
+- Next: Dispatch parallel tasks for Stage 2 (Tech Document Generation)
+```
+
+## Reference Guides
+
+### Platform Detection Reference
+
+#### Multiple Platforms in Same Project
+
+If a project contains multiple platforms (e.g., web + backend + mobile):
+- Detect each platform separately
+- Assign unique platform_id for each
+- Include all platforms in manifest
+
+#### Monorepo Structure
+
+For monorepos with multiple packages:
+- Detect platforms in each package directory
+- Use relative paths for source_path
+- Example: `packages/web-app` → web-react platform
+
+#### Framework Version Detection
+
+Extract version information when available:
+- From package.json dependencies
+- From pom.xml version tags
+- Include in report but not in manifest (manifest focuses on structure)
+
+#### Platform Mapping to bizs-init
+
+Ensure consistency with modules.json by using standardized platform identifiers from `platform-mapping.json`:
+
+**Key Rules:**
+- `platform_id` format: `{{platform_type}}-{{framework}}` (e.g., `mobile-uniapp`, `web-vue`)
+- `platform_type` must match between techs-manifest.json and modules.json
+- `framework` maps to `platform_subtype` in modules.json
+
+**Example Mapping:**
+| platform_id | platform_type | framework | platform_subtype (for bizs-init) |
+|-------------|---------------|-----------|----------------------------------|
+| web-vue | web | vue | vue |
+| mobile-uniapp | mobile | uniapp | uniapp |
+| backend-spring | backend | spring | spring |
+
+---
+
+## Checklist
+
+- [ ] All platform indicators checked
+- [ ] Platform metadata extracted (platform_id, type, framework, language)
+- [ ] Configuration files identified and paths recorded
+- [ ] Convention files (eslint, prettier) identified
+- [ ] techs-manifest.json generated with valid JSON structure
+- [ ] **Source traceability**: All config_file paths recorded for downstream use
+- [ ] Output path verified
+- [ ] Results reported with platform summary
+