@fractary/core 0.7.24 → 0.7.26

package/templates/docs/guides/template.md

@@ -0,0 +1,58 @@
+# {{title}}
+
+## Overview
+
+{{overview}}
+
+## Prerequisites
+
+{{#prerequisites}}
+- {{.}}
+{{/prerequisites}}
+
+## Steps
+
+{{#steps}}
+### Step {{number}}: {{title}}
+
+{{description}}
+
+{{#code}}
+```{{language}}
+{{code}}
+```
+{{/code}}
+
+{{#note}}
+> **Note:** {{note}}
+{{/note}}
+
+{{#warning}}
+> **Warning:** {{warning}}
+{{/warning}}
+
+{{/steps}}
+
+## Verification
+
+{{verification}}
+
+## Troubleshooting
+
+{{#troubleshooting}}
+### {{problem}}
+
+**Solution:** {{solution}}
+{{/troubleshooting}}
+
+## Next Steps
+
+{{#next_steps}}
+- [{{title}}]({{path}})
+{{/next_steps}}
+
+## Related Guides
+
+{{#related}}
+- [{{title}}]({{path}})
+{{/related}}

package/templates/docs/guides/type.yaml

@@ -0,0 +1,61 @@
+# How-to Guide Type Definition
+
+id: guides
+display_name: How-to Guide
+description: Step-by-step tutorials and how-to guides
+
+output_path: docs/guides
+
+file_naming:
+  pattern: "GUIDE-{slug}.md"
+  slug_source: title
+  slug_max_length: 50
+
+frontmatter:
+  required_fields:
+    - title
+    - type
+    - date
+  optional_fields:
+    - author
+    - difficulty
+    - time_required
+    - tags
+    - related
+    - prerequisites
+  defaults:
+    type: guides
+    difficulty: intermediate
+
+structure:
+  required_sections:
+    - Overview
+    - Prerequisites
+    - Steps
+  optional_sections:
+    - Verification
+    - Troubleshooting
+    - Next Steps
+    - Related Guides
+  section_order:
+    - Overview
+    - Prerequisites
+    - Steps
+    - Verification
+    - Troubleshooting
+    - Next Steps
+    - Related Guides
+
+status:
+  allowed_values:
+    - draft
+    - review
+    - published
+    - outdated
+  default: draft
+
+index_config:
+  index_file: docs/guides/README.md
+  sort_by: title
+  sort_order: asc
+  entry_template: "- [{{title}}]({{relative_path}}) - {{difficulty}}"

package/templates/docs/infrastructure/standards.md

@@ -0,0 +1,15 @@
+# Infrastructure Documentation Standards
+
+## Required Conventions
+
+- ALWAYS document all resources
+- ALWAYS include deployment procedures
+- ALWAYS document security configuration
+- ALWAYS include runbook operations
+
+## Best Practices
+
+- Include architecture diagrams
+- Document monitoring and alerts
+- Maintain runbooks for common operations
+- Document incident response procedures

package/templates/docs/infrastructure/template.md

@@ -0,0 +1,90 @@
+# {{title}}
+
+## Overview
+
+{{overview}}
+
+## Architecture
+
+```mermaid
+{{diagram}}
+```
+
+## Resources
+
+{{#resources}}
+### {{name}}
+
+- **Type:** {{type}}
+- **Provider:** {{provider}}
+- **Region:** {{region}}
+- **Configuration:** {{configuration}}
+{{/resources}}
+
+## Networking
+
+{{networking}}
+
+## Security
+
+### Access Control
+
+{{access_control}}
+
+### Secrets Management
+
+{{secrets_management}}
+
+## Deployment
+
+### Prerequisites
+
+{{#deployment_prerequisites}}
+- {{.}}
+{{/deployment_prerequisites}}
+
+### Process
+
+{{deployment_process}}
+
+### Rollback
+
+{{rollback}}
+
+## Monitoring
+
+### Health Checks
+
+{{#health_checks}}
+- **{{name}}**: {{endpoint}} ({{interval}})
+{{/health_checks}}
+
+### Alerts
+
+{{#alerts}}
+- **{{name}}**: {{condition}} → {{action}}
+{{/alerts}}
+
+## Runbook
+
+### Common Operations
+
+{{#operations}}
+#### {{name}}
+
+{{description}}
+
+```bash
+{{command}}
+```
+{{/operations}}
+
+### Incident Response
+
+{{incident_response}}
+
+## Related
+
+{{#related}}
+- [{{title}}]({{path}})
+{{/related}}

package/templates/docs/infrastructure/type.yaml

@@ -0,0 +1,66 @@
+# Infrastructure Documentation Type Definition
+
+id: infrastructure
+display_name: Infrastructure Documentation
+description: Infrastructure, deployment, and operations documentation
+
+output_path: docs/infrastructure
+
+file_naming:
+  pattern: "INFRA-{slug}.md"
+  slug_source: title
+  slug_max_length: 50
+
+frontmatter:
+  required_fields:
+    - title
+    - type
+    - status
+    - date
+  optional_fields:
+    - owner
+    - environment
+    - tags
+    - related
+    - provider
+  defaults:
+    type: infrastructure
+    status: draft
+
+structure:
+  required_sections:
+    - Overview
+    - Resources
+    - Deployment
+  optional_sections:
+    - Architecture
+    - Networking
+    - Security
+    - Monitoring
+    - Runbook
+    - Related
+  section_order:
+    - Overview
+    - Architecture
+    - Resources
+    - Networking
+    - Security
+    - Deployment
+    - Monitoring
+    - Runbook
+    - Related
+
+status:
+  allowed_values:
+    - draft
+    - review
+    - approved
+    - production
+    - deprecated
+  default: draft
+
+index_config:
+  index_file: docs/infrastructure/README.md
+  sort_by: title
+  sort_order: asc
+  entry_template: "- [{{title}}]({{relative_path}}) - {{environment}} ({{status}})"

package/templates/docs/manifest.yaml

@@ -0,0 +1,114 @@
+# Core Doc Types Manifest
+#
+# This manifest lists all core document types available in Fractary.
+# The format matches .fractary/config.yaml's docs.custom_types section,
+# so users can extend with their own types using the same structure.
+#
+# Each type is a directory containing:
+#   - type.yaml     : Type definition (schema, frontmatter rules, file naming)
+#   - template.md   : Mustache template for document generation
+#   - standards.md  : Standards and conventions for this type
+#   - examples/     : (optional) Example documents
+
+version: "1.0"
+
+# Base URL for raw file access (used by remote tools/SDKs)
+base_url: https://raw.githubusercontent.com/fractary/core/main/templates/docs
+
+doc_types:
+  - id: adr
+    display_name: Architecture Decision Record
+    description: Documents significant architectural decisions, their context, and consequences
+    path: ./adr
+    url: ${base_url}/adr/type.yaml
+
+  - id: api
+    display_name: API Documentation
+    description: API reference documentation with endpoint specifications
+    path: ./api
+    url: ${base_url}/api/type.yaml
+
+  - id: architecture
+    display_name: Architecture Documentation
+    description: System architecture documentation with diagrams and component descriptions
+    path: ./architecture
+    url: ${base_url}/architecture/type.yaml
+
+  - id: audit
+    display_name: Audit Report
+    description: Security audits, compliance checks, and assessment reports
+    path: ./audit
+    url: ${base_url}/audit/type.yaml
+
+  - id: changelog
+    display_name: Changelog
+    description: Version history and release notes documentation
+    path: ./changelog
+    url: ${base_url}/changelog/type.yaml
+
+  - id: dataset
+    display_name: Dataset Documentation
+    description: Data schema and dataset documentation
+    path: ./dataset
+    url: ${base_url}/dataset/type.yaml
+
+  - id: etl
+    display_name: ETL Pipeline Documentation
+    description: ETL and data pipeline documentation
+    path: ./etl
+    url: ${base_url}/etl/type.yaml
+
+  - id: guides
+    display_name: How-To Guide
+    description: Step-by-step guides and tutorials
+    path: ./guides
+    url: ${base_url}/guides/type.yaml
+
+  - id: infrastructure
+    display_name: Infrastructure Documentation
+    description: Infrastructure, deployment, and operations documentation
+    path: ./infrastructure
+    url: ${base_url}/infrastructure/type.yaml
+
+  - id: standards
+    display_name: Standards & Conventions
+    description: Coding standards, style guides, and team conventions
+    path: ./standards
+    url: ${base_url}/standards/type.yaml
+
+  - id: testing
+    display_name: Testing Documentation
+    description: Test plans, test results, and QA documentation
+    path: ./testing
+    url: ${base_url}/testing/type.yaml
+
+  # Specification types (formerly in the spec plugin)
+  - id: spec-basic
+    display_name: Basic Specification
+    description: Minimal specification for simple tasks and quick changes
+    path: ./spec-basic
+    url: ${base_url}/spec-basic/type.yaml
+
+  - id: spec-feature
+    display_name: Feature Specification
+    description: Comprehensive specification for new feature development
+    path: ./spec-feature
+    url: ${base_url}/spec-feature/type.yaml
+
+  - id: spec-bug
+    display_name: Bug Fix Specification
+    description: Specification for bug investigation and fix
+    path: ./spec-bug
+    url: ${base_url}/spec-bug/type.yaml
+
+  - id: spec-api
+    display_name: API Specification
+    description: Specification for API design and implementation
+    path: ./spec-api
+    url: ${base_url}/spec-api/type.yaml
+
+  - id: spec-infrastructure
+    display_name: Infrastructure Specification
+    description: Specification for infrastructure and DevOps changes
+    path: ./spec-infrastructure
+    url: ${base_url}/spec-infrastructure/type.yaml

package/templates/docs/spec-api/standards.md

@@ -0,0 +1,53 @@
+# API Specification Standards
+
+## Required Conventions
+
+### 1. Overview
+- ALWAYS describe the API's purpose and target consumers
+- ALWAYS specify the base URL and API version
+- Include any prerequisite knowledge or dependencies
+
+### 2. Endpoints
+- ALWAYS document each endpoint with method, path, and description
+- ALWAYS include request parameters with types and required/optional status
+- ALWAYS include request body and response body examples as JSON
+- ALWAYS document all possible HTTP status codes per endpoint
+
+### 3. Authentication
+- ALWAYS specify the authentication mechanism (Bearer token, API key, OAuth, etc.)
+- Document how to obtain credentials
+- Include example headers
+
+### 4. Error Handling
+- ALWAYS document error response format
+- ALWAYS include a table of all error codes with descriptions
+- Include example error responses for common failure scenarios
+
+### 5. Testing
+- ALWAYS include test scenarios as checkable items
+- Cover happy paths, error paths, and edge cases
+- Include contract testing scenarios for API compatibility
+
+## Optional Section Guidelines
+
+### Rate Limiting
+- Include for public-facing or multi-tenant APIs
+- Document rate limit headers and behavior when exceeded
+- Specify per-endpoint limits if they differ
+
+### Versioning
+- Include when introducing breaking changes
+- Document the versioning strategy (URL path, header, query param)
+- Describe deprecation timelines for old versions
+
+### Data Models
+- Include for complex or shared data structures
+- Document field types, constraints, and relationships
+- Include validation rules
+
+## Best Practices
+
+- Use consistent naming conventions (camelCase, snake_case) across all endpoints
+- Document idempotency behavior for write operations
+- Include pagination details for list endpoints
+- Specify content types (application/json, multipart/form-data, etc.)

package/templates/docs/spec-api/template.md

@@ -0,0 +1,96 @@
+---
+title: "{{title}}"
+fractary_doc_type: spec-api
+status: {{status}}
+date: {{date}}
+{{#work_id}}
+work_id: "{{work_id}}"
+{{/work_id}}
+{{#work_type}}
+work_type: {{work_type}}
+{{/work_type}}
+source: {{source}}
+validation_status: not_validated
+tags: []
+---
+
+# {{title}}
+
+## Overview
+
+{{overview}}
+
+## Authentication
+
+{{authentication}}
+
+## Endpoints
+
+{{#endpoints}}
+### `{{method}} {{path}}`
+
+**Description:** {{description}}
+
+**Parameters:**
+
+{{#parameters}}
+- `{{name}}` ({{type}}, {{required}}): {{description}}
+{{/parameters}}
+
+**Request Body:**
+
+```json
+{{request_body}}
+```
+
+**Response:**
+
+```json
+{{response_body}}
+```
+
+{{/endpoints}}
+
+{{#data_models}}
+## Data Models
+
+{{data_models}}
+{{/data_models}}
+
+## Error Handling
+
+| Code | Message | Description |
+|------|---------|-------------|
+{{#errors}}
+| {{code}} | {{message}} | {{description}} |
+{{/errors}}
+
+{{#rate_limiting}}
+## Rate Limiting
+
+{{rate_limiting}}
+{{/rate_limiting}}
+
+{{#versioning}}
+## Versioning
+
+{{versioning}}
+{{/versioning}}
+
+## Testing
+
+{{#test_scenarios}}
+- [ ] {{.}}
+{{/test_scenarios}}
+
+{{#security_considerations}}
+## Security Considerations
+
+{{security_considerations}}
+{{/security_considerations}}
+
+{{#migration_guide}}
+## Migration Guide
+
+{{migration_guide}}
+{{/migration_guide}}

package/templates/docs/spec-api/type.yaml

@@ -0,0 +1,102 @@
+id: spec-api
+display_name: API Specification
+description: Specification for API design and implementation
+
+output_path: specs
+
+file_naming:
+  pattern: "WORK-{work_id}-{slug}.md"
+  auto_number: false
+  slug_source: title
+  slug_max_length: 50
+
+frontmatter:
+  required_fields:
+    - title
+    - fractary_doc_type
+    - status
+    - date
+  optional_fields:
+    - work_id
+    - work_type
+    - source
+    - validation_status
+    - tags
+    - author
+    - related
+    - changelog
+  defaults:
+    fractary_doc_type: spec-api
+    status: draft
+    source: conversation
+    validation_status: not_validated
+
+structure:
+  required_sections:
+    - Overview
+    - Endpoints
+    - Authentication
+    - Error Handling
+    - Testing
+  optional_sections:
+    - Rate Limiting
+    - Versioning
+    - Data Models
+    - Migration Guide
+    - Security Considerations
+    - References
+  section_order:
+    - Overview
+    - Authentication
+    - Endpoints
+    - Data Models
+    - Error Handling
+    - Rate Limiting
+    - Versioning
+    - Testing
+    - Security Considerations
+    - Migration Guide
+    - References
+
+status:
+  allowed_values:
+    - draft
+    - review
+    - approved
+    - in-progress
+    - completed
+    - archived
+  default: draft
+
+index_config:
+  index_file: specs/README.md
+  sort_by: date
+  sort_order: desc
+  entry_template: "- [**{{work_id}}**: {{title}}]({{relative_path}}) — {{status}}"
+
+archive:
+  enabled: true
+  source: archive
+  trigger: on_status_change
+  trigger_statuses:
+    - archived
+  verify_checksum: true
+  delete_original: true
+
+work_linking:
+  enabled: true
+  comment_on_create: true
+  comment_on_archive: true
+  require_closed_for_archive: true
+
+refinement:
+  enabled: true
+  post_questions_to_work_item: true
+  maintain_changelog: true
+
+fulfillment:
+  enabled: true
+  check_acceptance_criteria: true
+  check_files_modified: true
+  check_tests_added: true
+  check_docs_updated: true

package/templates/docs/spec-basic/standards.md

@@ -0,0 +1,24 @@
+# Basic Specification Standards
+
+## Required Conventions
+
+### 1. Objective
+- ALWAYS provide a single clear statement of what needs to be accomplished
+- Keep it concise — one to three sentences maximum
+- NEVER leave the objective as a placeholder
+
+### 2. Requirements
+- ALWAYS write requirements as checkable items (- [ ] format)
+- Keep the list short and focused (typically 2-5 items)
+- Each requirement should be independently verifiable
+
+### 3. Acceptance Criteria
+- ALWAYS write acceptance criteria as verifiable checkboxes
+- Criteria should directly map to requirements
+- Include at least one criterion per requirement
+
+## Best Practices
+
+- Use the basic template for simple, well-understood tasks
+- If you find yourself adding many optional sections, consider upgrading to spec-feature
+- Keep the spec short — if it exceeds one page, the task may need a more detailed template