grimoire-framework 1.0.0

package/.grimoire/infrastructure/templates/project-docs/source-tree-tmpl.md

@@ -0,0 +1,179 @@
+# {{PROJECT_NAME}} Source Tree Standard
+
+> **Auto-generated by grimoire** on {{GENERATED_DATE}}
+> **Mode:** {{INSTALLATION_MODE}}
+> **Tech Stack:** {{TECH_STACK}}
+
+## Overview
+
+This document defines the directory structure and file organization standards for **{{PROJECT_NAME}}**.
+
+## Directory Structure
+
+```
+{{PROJECT_NAME}}/
+├── .grimoire/                    # grimoire configuration
+│   └── core-config.yaml           # Project configuration
+│
+├── .github/                       # GitHub configuration
+│   └── workflows/                 # CI/CD workflows
+│       ├── quality-gates.yml      # Quality checks
+│       └── deploy.yml             # Deployment automation
+│
+├── docs/                          # Documentation
+│   ├── architecture/              # Project architecture docs
+│   │   ├── source-tree.md         # THIS FILE
+│   │   ├── coding-standards.md    # Coding conventions
+│   │   └── tech-stack.md          # Technology decisions
+│   ├── guides/                    # User guides
+│   └── api/                       # API documentation
+│
+{{#if IS_NODE}}
+├── src/                           # Source code
+│   ├── index.{{FILE_EXT}}         # Entry point
+│   ├── config/                    # Configuration modules
+│   ├── services/                  # Business logic
+│   ├── utils/                     # Utility functions
+│   └── types/                     # TypeScript types (if applicable)
+│
+├── tests/                         # Test files
+│   ├── unit/                      # Unit tests
+│   ├── integration/               # Integration tests
+│   └── fixtures/                  # Test fixtures
+│
+├── scripts/                       # Build and utility scripts
+│
+├── package.json                   # Node.js dependencies
+├── tsconfig.json                  # TypeScript config (if applicable)
+{{/if}}
+{{#if IS_PYTHON}}
+├── {{PYTHON_PACKAGE_NAME}}/       # Python package
+│   ├── __init__.py                # Package init
+│   ├── main.py                    # Entry point
+│   ├── config/                    # Configuration
+│   ├── services/                  # Business logic
+│   └── utils/                     # Utilities
+│
+├── tests/                         # Test files
+│   ├── unit/                      # Unit tests
+│   ├── integration/               # Integration tests
+│   └── conftest.py                # Pytest configuration
+│
+├── requirements.txt               # Python dependencies
+├── pyproject.toml                 # Project configuration
+{{/if}}
+{{#if IS_GO}}
+├── cmd/                           # Command entry points
+│   └── {{PROJECT_NAME}}/
+│       └── main.go                # Main entry point
+│
+├── internal/                      # Private packages
+│   ├── config/                    # Configuration
+│   ├── services/                  # Business logic
+│   └── utils/                     # Utilities
+│
+├── pkg/                           # Public packages
+│
+├── go.mod                         # Go modules
+├── go.sum                         # Dependency checksums
+{{/if}}
+│
+├── .gitignore                     # Git ignore rules
+├── .env.example                   # Environment template
+└── README.md                      # Project documentation
+```
+
+## File Placement Rules
+
+### Documentation Files
+
+| File Pattern | Location | Purpose |
+|--------------|----------|---------|
+| `*.md` (project docs) | `docs/` | Project documentation |
+| Architecture docs | `docs/architecture/` | Technical standards |
+| User guides | `docs/guides/` | How-to documentation |
+| API docs | `docs/api/` | API reference |
+
+### Source Code
+
+| File Pattern | Location | Purpose |
+|--------------|----------|---------|
+{{#if IS_NODE}}
+| `*.js`, `*.ts` | `src/` | Application source code |
+| `*.test.js`, `*.test.ts` | `tests/` | Test files |
+| `*.d.ts` | `src/types/` | TypeScript declarations |
+{{/if}}
+{{#if IS_PYTHON}}
+| `*.py` | `{{PYTHON_PACKAGE_NAME}}/` | Application source code |
+| `test_*.py` | `tests/` | Test files |
+{{/if}}
+{{#if IS_GO}}
+| `*.go` | `cmd/`, `internal/`, `pkg/` | Go source files |
+| `*_test.go` | Same as source | Test files |
+{{/if}}
+
+### Configuration Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `.grimoire/core-config.yaml` | Root | grimoire configuration |
+| `.env`, `.env.*` | Root | Environment variables |
+| `.gitignore` | Root | Git ignore rules |
+{{#if IS_NODE}}
+| `package.json` | Root | Node.js dependencies |
+| `tsconfig.json` | Root | TypeScript configuration |
+| `.eslintrc.*` | Root | ESLint configuration |
+| `.prettierrc` | Root | Prettier configuration |
+{{/if}}
+{{#if IS_PYTHON}}
+| `pyproject.toml` | Root | Python project config |
+| `requirements.txt` | Root | Python dependencies |
+| `.flake8` | Root | Flake8 configuration |
+{{/if}}
+
+## Anti-Patterns (Files NOT Allowed at Root)
+
+The following files should NOT be placed at the project root:
+
+| Pattern | Correct Location | Reason |
+|---------|------------------|--------|
+| `*.md` (except README) | `docs/` | Documentation belongs in docs |
+{{#if IS_NODE}}
+| `*.js`, `*.ts` (source) | `src/` | Source code belongs in src |
+| `*.test.js` | `tests/` | Tests belong in tests |
+{{/if}}
+{{#if IS_PYTHON}}
+| `*.py` (source) | `{{PYTHON_PACKAGE_NAME}}/` | Source code belongs in package |
+| `test_*.py` | `tests/` | Tests belong in tests |
+{{/if}}
+| Temporary files | N/A | Should not be committed |
+
+## Naming Conventions
+
+### Directories
+
+- Use **kebab-case** for directory names: `my-feature/`
+- Use lowercase: `services/` not `Services/`
+
+### Files
+
+{{#if IS_NODE}}
+- Source files: **kebab-case** - `user-service.js`
+- Test files: **kebab-case** with `.test` suffix - `user-service.test.js`
+- React components: **PascalCase** - `UserProfile.tsx`
+{{/if}}
+{{#if IS_PYTHON}}
+- Source files: **snake_case** - `user_service.py`
+- Test files: **snake_case** with `test_` prefix - `test_user_service.py`
+{{/if}}
+{{#if IS_GO}}
+- Source files: **snake_case** - `user_service.go`
+- Test files: **snake_case** with `_test` suffix - `user_service_test.go`
+{{/if}}
+
+---
+
+*Generated by grimoire Documentation Integrity System*
+*Template Version: 1.0.0*
+
+

package/.grimoire/infrastructure/templates/project-docs/tech-stack-tmpl.md

@@ -0,0 +1,269 @@
+# {{PROJECT_NAME}} Tech Stack
+
+> **Auto-generated by grimoire** on {{GENERATED_DATE}}
+> **Mode:** {{INSTALLATION_MODE}}
+
+## Overview
+
+This document describes the technology stack and tooling decisions for **{{PROJECT_NAME}}**.
+
+---
+
+## Core Technologies
+
+### Runtime & Language
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+{{#if IS_NODE}}
+| Node.js | {{NODE_VERSION}} | JavaScript runtime |
+{{#if IS_TYPESCRIPT}}
+| TypeScript | {{TYPESCRIPT_VERSION}} | Type-safe JavaScript |
+{{/if}}
+{{/if}}
+{{#if IS_PYTHON}}
+| Python | {{PYTHON_VERSION}} | Programming language |
+{{/if}}
+{{#if IS_GO}}
+| Go | {{GO_VERSION}} | Programming language |
+{{/if}}
+{{#if IS_RUST}}
+| Rust | {{RUST_VERSION}} | Programming language |
+{{/if}}
+
+### Package Management
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+{{#if IS_NODE}}
+| npm | {{NPM_VERSION}} | Package manager |
+{{/if}}
+{{#if IS_PYTHON}}
+| pip | Latest | Package installer |
+| poetry | {{POETRY_VERSION}} | Dependency management (optional) |
+{{/if}}
+{{#if IS_GO}}
+| Go Modules | Built-in | Dependency management |
+{{/if}}
+
+---
+
+## Development Tools
+
+### Code Quality
+
+| Tool | Purpose | Configuration |
+|------|---------|---------------|
+{{#if IS_NODE}}
+| ESLint | Linting | `.eslintrc.js` |
+| Prettier | Formatting | `.prettierrc` |
+{{#if IS_TYPESCRIPT}}
+| TypeScript | Type checking | `tsconfig.json` |
+{{/if}}
+{{/if}}
+{{#if IS_PYTHON}}
+| Black | Formatting | `pyproject.toml` |
+| Flake8 | Linting | `.flake8` |
+| mypy | Type checking | `mypy.ini` |
+{{/if}}
+{{#if IS_GO}}
+| gofmt | Formatting | Built-in |
+| golint | Linting | N/A |
+| go vet | Static analysis | Built-in |
+{{/if}}
+
+### Testing
+
+| Tool | Purpose | Location |
+|------|---------|----------|
+{{#if IS_NODE}}
+| Jest | Unit testing | `tests/unit/` |
+| Supertest | API testing | `tests/integration/` |
+{{/if}}
+{{#if IS_PYTHON}}
+| pytest | Testing framework | `tests/` |
+| pytest-cov | Coverage | `pytest.ini` |
+{{/if}}
+{{#if IS_GO}}
+| go test | Testing framework | `*_test.go` files |
+{{/if}}
+
+### Build Tools
+
+| Tool | Purpose |
+|------|---------|
+{{#if IS_NODE}}
+{{#if IS_TYPESCRIPT}}
+| tsc | TypeScript compilation |
+{{/if}}
+| esbuild / rollup | Bundling (if needed) |
+{{/if}}
+{{#if IS_PYTHON}}
+| setuptools | Package building |
+| wheel | Distribution format |
+{{/if}}
+{{#if IS_GO}}
+| go build | Compilation |
+{{/if}}
+
+---
+
+## Infrastructure
+
+### Version Control
+
+| Service | Purpose |
+|---------|---------|
+| Git | Version control |
+| GitHub | Repository hosting |
+| GitHub Actions | CI/CD |
+
+### Deployment
+
+| Platform | Environment | Branch |
+|----------|-------------|--------|
+{{#if DEPLOYMENT_PLATFORM}}
+| {{DEPLOYMENT_PLATFORM}} | Production | `{{PRODUCTION_BRANCH}}` |
+{{#if HAS_STAGING}}
+| {{DEPLOYMENT_PLATFORM}} | Staging | `{{STAGING_BRANCH}}` |
+{{/if}}
+{{else}}
+| TBD | Production | `main` |
+{{/if}}
+
+### Database (if applicable)
+
+| Technology | Purpose | Environment |
+|------------|---------|-------------|
+{{#if DATABASE}}
+| {{DATABASE}} | Primary database | All |
+{{/if}}
+{{#if CACHE}}
+| {{CACHE}} | Caching layer | All |
+{{/if}}
+
+---
+
+## Dependencies
+
+### Production Dependencies
+
+{{#if IS_NODE}}
+Key dependencies from `package.json`:
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+{{#each DEPENDENCIES}}
+| {{this.name}} | {{this.version}} | {{this.purpose}} |
+{{/each}}
+{{/if}}
+
+{{#if IS_PYTHON}}
+Key dependencies from `requirements.txt`:
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+{{#each DEPENDENCIES}}
+| {{this.name}} | {{this.version}} | {{this.purpose}} |
+{{/each}}
+{{/if}}
+
+### Development Dependencies
+
+| Package | Purpose |
+|---------|---------|
+{{#each DEV_DEPENDENCIES}}
+| {{this.name}} | {{this.purpose}} |
+{{/each}}
+
+---
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `.grimoire/core-config.yaml` | grimoire configuration |
+| `.env.example` | Environment template |
+| `.gitignore` | Git ignore rules |
+{{#if IS_NODE}}
+| `package.json` | Node.js project config |
+{{#if IS_TYPESCRIPT}}
+| `tsconfig.json` | TypeScript config |
+{{/if}}
+| `.eslintrc.js` | ESLint rules |
+| `.prettierrc` | Prettier config |
+{{/if}}
+{{#if IS_PYTHON}}
+| `pyproject.toml` | Python project config |
+| `requirements.txt` | Dependencies |
+| `.flake8` | Flake8 config |
+{{/if}}
+{{#if IS_GO}}
+| `go.mod` | Go modules |
+| `go.sum` | Dependency checksums |
+{{/if}}
+
+---
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `NODE_ENV` / `ENV` | Environment name | Yes |
+{{#each ENV_VARS}}
+| `{{this.name}}` | {{this.description}} | {{this.required}} |
+{{/each}}
+
+See `.env.example` for a complete list.
+
+---
+
+## Upgrade Guidelines
+
+### Language/Runtime Updates
+
+1. Check release notes for breaking changes
+2. Update version in configuration files
+3. Run full test suite
+4. Update CI/CD configuration
+5. Document changes in CHANGELOG
+
+### Dependency Updates
+
+1. Review changelogs for security fixes
+2. Update one dependency at a time
+3. Run tests after each update
+4. Commit with clear message
+
+```bash
+{{#if IS_NODE}}
+# Check for updates
+npm outdated
+
+# Update specific package
+npm update <package-name>
+{{/if}}
+{{#if IS_PYTHON}}
+# Check for updates
+pip list --outdated
+
+# Update specific package
+pip install --upgrade <package-name>
+{{/if}}
+```
+
+---
+
+## Security Considerations
+
+- [ ] Dependencies scanned for vulnerabilities
+- [ ] Environment variables not committed
+- [ ] Secrets stored securely
+- [ ] HTTPS enforced in production
+
+---
+
+*Generated by grimoire Documentation Integrity System*
+*Template Version: 1.0.0*
+
+