Project Documentation System Template

A comprehensive, git-native documentation system for AI-first software development that seamlessly migrates to Confluence and integrates with traditional governance reporting.

This is a template repository. Click "Use this template" to create a new project with this documentation structure.

Overview

This template provides a complete documentation system designed to:

✅ Support spec-driven, AI-first development workflows
✅ Version control all documentation in Git with markdown
✅ Automatically sync to Confluence when ready
✅ Integrate with Jira for issue tracking
✅ Generate governance reports for traditional consultancies (Excel, PowerPoint)
✅ Provide comprehensive metadata for traceability

Quick Start

1. Use This Template

Click the "Use this template" button on GitHub, or:

git clone https://github.com/yourusername/project-docs-template.git my-new-project
cd my-new-project
rm -rf .git
git init

2. Configure Your Project

Update .confluence/config.yml:

confluence:
  url: "https://yourcompany.atlassian.net/wiki"
  cloud_id: "your-cloud-id-here"  # Find at: yourcompany.atlassian.net/_edge/tenant_info

spaces:
  requirements:
    key: YOURSPACE              # Your Confluence space key
    name: "Your Project Name"
    parent_page: "Project Requirements"

jira:
  url: "https://yourcompany.atlassian.net"
  default_project: "PROJ"       # Your Jira project key

Set Environment Variables:

# Required for Confluence sync
export CONFLUENCE_USERNAME="your-email@company.com"
export CONFLUENCE_API_TOKEN="your-api-token"

Generate API token at: https://id.atlassian.com/manage-profile/security/api-tokens

Update User Mappings:

In .confluence/config.yml, update the user_mappings section with your team:

user_mappings:
  "Your Name":
    email: "your.email@company.com"
    account_id: "your-atlassian-account-id"  # From Jira user profile URL

3. Install Dependencies

pip install -r requirements.txt

4. Start Documenting

For Engineers:

# Create a new feature spec from template
cp templates/feature-spec-template.md specifications/features/my-new-feature.md

# Edit and fill in all sections
# (Use Claude Code, Cursor, or your favorite editor)

# Validate your spec
python .claude/skills/validate-docs/scripts/validate_docs.py --files specifications/features/my-new-feature.md

# Commit and create PR
git add specifications/features/my-new-feature.md
git commit -m "Add feature spec for X"
git push origin feature/my-new-feature

For Product Managers:

Ask Claude: "Create a BRD for [your requirement]"

Or use the script:

python .claude/skills/doc-generator/scripts/create_doc.py --type brd --name my-requirement

For Stakeholders:

Browse markdown files directly in GitHub
View in Confluence after sync
Access automated reports (Excel, PowerPoint)

Claude Code Skills

This template includes three specialized Claude Code skills that make documentation management effortless:

🔍 Validate Documentation

Automatically validates markdown files for proper structure and metadata.

Ask Claude: "Validate my documentation"

Features:

Frontmatter validation (required fields, YAML syntax)
Cross-reference checking (finds broken links)
Confluence compatibility checks
Auto-fix for common issues

Learn more →

☁️ Confluence Sync

Syncs validated markdown to Confluence spaces with proper formatting.

Ask Claude: "Sync the feature specs to Confluence"

Features:

Markdown to Confluence conversion
Page hierarchy management
Metadata and label application
Dry-run mode for testing

Learn more →

📝 Documentation Generator

Creates new documents from templates with proper structure.

Ask Claude: "Create a feature spec for user authentication"

Features:

Template selection guidance
Automatic frontmatter generation
File naming and location management
Integration with validation

Learn more →

Using the Skills: Simply ask Claude naturally - the skills activate automatically based on your request. For detailed documentation, see .claude/skills/README.md.

Project Structure

your-project/
├── .claude/
│   └── skills/                       # Claude Code skills
│       ├── validate-docs/            # Documentation validation skill
│       ├── confluence-sync/          # Confluence sync skill
│       ├── doc-generator/            # Document creation skill
│       └── README.md                 # Skills documentation
├── .confluence/
│   └── config.yml                    # Confluence and integration configuration
├── .github/
│   └── workflows/
│       ├── validate-docs.yml         # PR validation
│       └── confluence-sync.yml       # Auto-sync on merge
├── templates/
│   ├── feature-spec-template.md      # Feature specification template
│   ├── adr-template.md               # Architecture decision template
│   ├── requirement-template.md       # Business requirement template
│   └── technical-pattern-template.md # Technical pattern template
├── requirements/
│   ├── README.md                     # Requirements space homepage
│   ├── _space.yml                    # Space configuration
│   ├── business-requirements/        # Business requirements
│   └── functional-requirements/      # Functional requirements
├── specifications/
│   ├── README.md                     # Specifications space homepage
│   ├── _space.yml                    # Space configuration
│   ├── architecture/                 # Architecture docs
│   │   └── adrs/                     # Architecture Decision Records
│   ├── features/                     # Feature specifications
│   └── technical-patterns/           # Reusable patterns
├── examples/                         # Example documents
├── docs/                             # System documentation
├── requirements.txt                  # Python dependencies
└── README.md                         # This file

Documentation Types

Business Requirements

High-level business needs, user personas, use cases.

Template: requirement-template.md Example: Unified Client Portal

Key Sections:

Problem statement and desired outcome
User personas and use cases
Functional and non-functional requirements
Success metrics and KPIs
Constraints and assumptions

Feature Specifications

Detailed technical specifications for features.

Template: feature-spec-template.md Example: Client Document Inventory

Key Sections:

Business context and user stories
Technical architecture and data models
API contracts and endpoints
Security and performance requirements
AI build instructions (for Claude Code, Copilot)
Testing and deployment guidance

Architecture Decision Records (ADRs)

Document significant technical decisions.

Template: adr-template.md Example: ADR-001: GCP Selection

Key Sections:

Context and problem statement
Options considered with pros/cons
Decision and rationale
Consequences and trade-offs
Implementation notes

Technical Patterns

Reusable implementation patterns and code examples.

Template: technical-pattern-template.md

Key Sections:

Pattern intent and purpose
When to use / when not to use
Code examples (Python, TypeScript)
Testing strategy
Common pitfalls

Workflow

Creating New Documentation

Choose the right template based on document type
Copy template to appropriate directory
Fill in all sections - Don't skip required fields
Add metadata - Confluence space, Jira project, status, etc.
Link related docs - Cross-reference other documents
Validate - Run validation script
Create PR - Submit for review
Merge - Auto-syncs to Confluence

Document Lifecycle

draft → in-review → approved → implemented

Update the status field in frontmatter as document progresses.

Validation

All documents are validated on PR:

# Validate all documents
python .claude/skills/validate-docs/scripts/validate_docs.py

# Validate specific files
python .claude/skills/validate-docs/scripts/validate_docs.py --files path/to/doc.md

# Verbose output
python .claude/skills/validate-docs/scripts/validate_docs.py --verbose

# Auto-fix common issues
python .claude/skills/validate-docs/scripts/validate_docs.py --fix

Validation Checks:

Required frontmatter fields present
Valid YAML syntax
Status is valid enum
Cross-references point to existing files
No Confluence-incompatible markdown features
Proper date formats

Confluence Sync

Documentation syncs to Confluence automatically on merge to main:

# Manual sync (dry-run)
python .claude/skills/confluence-sync/scripts/convert_to_confluence.py --dry-run

# Manual sync (for real)
python .claude/skills/confluence-sync/scripts/convert_to_confluence.py

# Sync specific files
python .claude/skills/confluence-sync/scripts/convert_to_confluence.py --files path/to/doc.md

# Force update even if unchanged
python .claude/skills/confluence-sync/scripts/convert_to_confluence.py --force

Sync Process:

Converts markdown to Confluence storage format
Creates or updates pages in Confluence
Sets page hierarchy (parent/child relationships)
Applies labels from frontmatter
Fixes cross-references to Confluence page links
Preserves page history

Frontmatter Metadata

All documents require YAML frontmatter:

---
# Confluence Configuration
confluence:
  space: PROJSPEC              # Space key
  parent: Features             # Parent page title
  labels: [feature, mvp]       # Page labels

# Jira Configuration (optional)
jira:
  project: PROJ                # Project key
  issue_type: Epic             # Issue type
  components: [Backend]        # Components
  labels: [feature]            # Labels

# Document Metadata
title: "Feature: My Feature"
status: draft                  # draft, in-review, approved, implemented
version: 1.0
author: Your Name
created: 2025-10-22
last_updated: 2025-10-22
reviewers: [Reviewer1, Reviewer2]
related_docs:
  - path/to/related-doc.md
---

AI-First Development

This documentation system is optimized for AI assistants like Claude Code:

AI Build Instructions

Every feature spec includes an AI Build Instructions section with:

Reference implementations
Step-by-step build process
Code style and patterns
Common pitfalls to avoid

Using with Claude Code

# Claude can read the spec and implement it
claude code "Implement the feature specified in specifications/features/document-inventory.md"

# Claude can validate against acceptance criteria
claude code "Test the document upload feature and verify all acceptance criteria"

# Claude can update documentation
claude code "Update the ADR for database selection with our final decision"

Using with GitHub Copilot

Open a feature spec in your editor and Copilot will:

Suggest implementations based on the spec
Generate tests from acceptance criteria
Propose API endpoints from contracts
Create data models from entity definitions

Configuration

Finding Your Confluence Cloud ID

Navigate to: https://yourcompany.atlassian.net/_edge/tenant_info
Copy the cloudId value
Add to .confluence/config.yml

Finding Jira Custom Field IDs

Use the Jira REST API:

curl -u your-email@company.com:your-api-token \
  https://yourcompany.atlassian.net/rest/api/3/field \
  | jq '.[] | select(.custom==true) | {id, name}'

Finding Atlassian Account IDs

Go to Jira > People
Click on a user
Copy account ID from the URL: accountId=XXXXXX

Documentation Standards

Markdown Style

Use ATX-style headers (# Header)
Use fenced code blocks with language specification
Use tables for structured data
Use task lists for checklists
Avoid HTML (not Confluence-compatible)

Writing Guidelines

Be specific: "< 2 seconds" not "fast"
Be testable: Define clear acceptance criteria
Be complete: Fill in all template sections
Be consistent: Follow existing examples
Link generously: Cross-reference related docs

Code Examples

Provide both Python and TypeScript examples
Include complete, runnable code
Add comments explaining non-obvious parts
Show error handling
Include tests

Troubleshooting

Validation Errors

Error: "Missing required field: title" Fix: Add title: "Document Title" to frontmatter

Error: "Invalid status value" Fix: Use one of: draft, in-review, approved, implemented, deprecated

Error: "Broken link to path/to/doc.md" Fix: Verify the file exists and path is correct

Sync Issues

Issue: "Page not found in Confluence" Fix: Ensure parent page exists, check space key

Issue: "Permission denied" Fix: Verify API token has write access to space

Issue: "Invalid Confluence storage format" Fix: Check for unsupported markdown features (mermaid, math)

GitHub Actions Setup

After creating your repository from this template:

Add Repository Secrets:
- Go to Settings > Secrets and variables > Actions
- Add CONFLUENCE_USERNAME (your email)
- Add CONFLUENCE_API_TOKEN (from Atlassian)
Enable GitHub Actions:
- Go to Actions tab
- Enable workflows if prompted
Test Validation:
- Create a test PR
- Verify validation workflow runs
Test Sync (optional):
- Set sync.dry_run: false in .confluence/config.yml
- Merge a PR to main
- Check Confluence for synced pages

Customization

Adding New Document Types

Create template in templates/
Add example in examples/
Update doc-generator skill configuration
Update validation rules if needed

Extending Validation

Edit .claude/skills/validate-docs/scripts/utils/validators.py to add custom validation rules.

Custom Confluence Macros

Edit .claude/skills/confluence-sync/scripts/utils/markdown_converter.py to add custom markdown → Confluence macro conversions.

Additional Resources

Setup Guide - Detailed setup instructions
User Guide - Creating and managing specs
Developer Guide - Extending the system
API Configuration - API setup details
Skills Documentation - Claude Code skills

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Run validation
Submit a pull request

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

License

MIT License - See LICENSE file for details

Acknowledgments

Inspired by AI-first development practices
Built for modern, cloud-native architectures
Designed for seamless Confluence integration
Optimized for Claude Code and GitHub Copilot

Template Features

✅ Complete Directory Structure - Ready to use ✅ 4 Comprehensive Templates - Feature specs, BRDs, ADRs, patterns ✅ 3 Claude Code Skills - Validation, sync, generation ✅ GitHub Actions - Automated validation and sync ✅ Example Documents - Real-world examples to follow ✅ Configuration Files - Pre-configured with sensible defaults ✅ Documentation - Complete setup and usage guides

Next Steps

Use this template to create your project
Configure .confluence/config.yml with your details
Set environment variables for Confluence API
Start documenting using templates and Claude Code
Enable GitHub Actions for automation
Invite your team and start collaborating

Happy documenting! 📝

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.claude/skills		.claude/skills
.confluence		.confluence
.github/workflows		.github/workflows
examples		examples
requirements		requirements
specifications		specifications
templates		templates
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CLAUDE.md		CLAUDE.md
README.md		README.md
package.json		package.json
requirements.txt		requirements.txt

chrisp-mp/spec-driven-dev-template

Folders and files

Latest commit

History

Repository files navigation

Project Documentation System Template

Overview

Quick Start

1. Use This Template

2. Configure Your Project

3. Install Dependencies

4. Start Documenting

Claude Code Skills

🔍 Validate Documentation

☁️ Confluence Sync

📝 Documentation Generator

Project Structure

Documentation Types

Business Requirements

Feature Specifications

Architecture Decision Records (ADRs)

Technical Patterns

Workflow

Creating New Documentation

Document Lifecycle

Validation

Confluence Sync

Frontmatter Metadata

AI-First Development

AI Build Instructions

Using with Claude Code

Using with GitHub Copilot

Configuration

Finding Your Confluence Cloud ID

Finding Jira Custom Field IDs

Finding Atlassian Account IDs

Documentation Standards

Markdown Style

Writing Guidelines

Code Examples

Troubleshooting

Validation Errors

Sync Issues

GitHub Actions Setup

Customization

Adding New Document Types

Extending Validation

Custom Confluence Macros

Additional Resources

Contributing

Support

License

Acknowledgments

Template Features

Next Steps

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages