Skip to content

Commit cab69ad

Browse files
ashleyshawashleyshaw
committed
docs: add README files for .github/schemas and .github/projects directories
- .github/schemas/README.md documents JSON schemas and configuration templates * Explains purpose and usage of theme-config.schema.json * Documents theme-config.example.json template * Provides guidelines for adding new schemas - .github/projects/README.md documents active Copilot projects * Explains project status tracking with indicators * Documents context-reduction.md project * Provides project workflow and best practices * Shows example project structure Improves discoverability and maintainability of new directory structure.
1 parent f06acb1 commit cab69ad

File tree

2 files changed

+236
-0
lines changed

2 files changed

+236
-0
lines changed

‎.github/projects/README.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Projects Directory
2+
3+
This directory contains AI/Copilot projects currently in development or being tracked.
4+
5+
## Purpose
6+
7+
Track active initiatives and work-in-progress projects that improve the block-theme-scaffold repository. Projects in this directory are ongoing efforts that will eventually be archived to the reports directory once completed.
8+
9+
## Status Tracking
10+
11+
Projects use status indicators to show current progress:
12+
13+
- **✅ Complete** - Task or phase finished
14+
- **🔄 In Progress** - Actively being worked on
15+
- **⏳ Pending** - Waiting to be started
16+
- **❌ Blocked** - Blocked by dependencies or issues
17+
18+
## Current Projects
19+
20+
### context-reduction.md
21+
22+
**Status:** 🔄 In Progress (Phase 4 of 5)
23+
24+
**Purpose:** Comprehensive plan to reduce token bloat and context usage in the block-theme-scaffold repository.
25+
26+
**Phases:**
27+
- ✅ Phase 1: Delete Model-Specific Files (~495 lines removed)
28+
- ✅ Phase 2: Consolidate Documentation (merged governance and development docs)
29+
- ✅ Phase 3: Optimize Core Index Files (reduced AGENTS.md, agent.md, prompts.md)
30+
- 🔄 Phase 4: Streamline Instruction Files (currently in progress)
31+
- ⏳ Phase 5: Reduce Frontmatter References (pending)
32+
33+
**Expected Outcome:** Reduce context token usage by 40-50% while maintaining documentation quality.
34+
35+
**Owner:** AI Agents / Copilot
36+
37+
**Last Updated:** December 9, 2025
38+
39+
## Project Workflow
40+
41+
### Starting a New Project
42+
43+
1. Create a markdown file in `.github/projects/`
44+
- Filename: `{project-name}.md`
45+
- Example: `context-reduction.md`
46+
47+
2. Include project header:
48+
```markdown
49+
# Project Title
50+
51+
**Status:** ⏳ Pending
52+
**Owner:** [Copilot/AI Agent/Developer Name]
53+
**Start Date:** YYYY-MM-DD
54+
**Expected Completion:** YYYY-MM-DD
55+
```
56+
57+
3. Document project sections:
58+
- Objective/Goals
59+
- Scope/Deliverables
60+
- Tasks/Phases (with status indicators)
61+
- Success Criteria
62+
- Related Files
63+
64+
4. Track progress with status updates:
65+
- Update status regularly
66+
- Mark completed tasks
67+
- Note blockers or issues
68+
69+
### Completing a Project
70+
71+
1. Mark all tasks as ✅ Complete
72+
2. Update status to `✅ Complete`
73+
3. Add completion date
74+
4. Move file to `.github/reports/` (rename to match report naming convention)
75+
5. Create archive entry in reports directory
76+
77+
### Archive Strategy
78+
79+
- Keep projects in this directory while active
80+
- Move to `.github/reports/` when 100% complete
81+
- Archive projects older than 3 months (if still incomplete)
82+
- Review archived projects quarterly for reference
83+
84+
## Moving to Reports
85+
86+
When a project is complete:
87+
88+
```bash
89+
# Move completed project to reports
90+
git mv .github/projects/{project-name}.md .github/reports/{project-name}-report.md
91+
92+
# Update file with completion date and final status
93+
# Add "report" to filename to indicate it's archived
94+
```
95+
96+
## Related Files
97+
98+
- [FILE_ORGANIZATION.md](../FILE_ORGANIZATION.md) - Overall file organization guide
99+
- [.github/reports/](../reports/README.md) - Completed project reports
100+
- [docs/](../../docs/README.md) - Permanent documentation
101+
- [GOVERNANCE.md](../../docs/GOVERNANCE.md) - Project governance
102+
103+
## Best Practices
104+
105+
1. **Be Specific**: Clearly define project goals and deliverables
106+
2. **Break Down Work**: Divide projects into manageable phases or tasks
107+
3. **Track Progress**: Update status regularly (at least weekly)
108+
4. **Link Dependencies**: Reference related files and dependencies
109+
5. **Document Decisions**: Record why decisions were made
110+
6. **Estimate Timelines**: Provide target dates for phases
111+
7. **Archive Successfully**: Move completed projects to reports promptly
112+
113+
## Example Project Structure
114+
115+
```markdown
116+
# Project: Performance Optimization Sprint
117+
118+
**Status:** 🔄 In Progress
119+
**Owner:** Copilot Code Review Agent
120+
**Start Date:** 2025-12-01
121+
**Expected Completion:** 2025-12-15
122+
123+
## Objective
124+
125+
Reduce Lighthouse performance score to 90+ and bundle size by 20%.
126+
127+
## Phases
128+
129+
### Phase 1: Bundle Analysis
130+
- 🔄 Generate webpack-bundle-analyzer report
131+
- ⏳ Identify optimization opportunities
132+
- ⏳ Prioritize high-impact changes
133+
134+
### Phase 2: Code Splitting
135+
- ⏳ Implement lazy loading for editor.js
136+
- ⏳ Separate theme.js utilities
137+
- ⏳ Test performance impact
138+
139+
### Phase 3: Testing & Validation
140+
- ⏳ Run lighthouse audit
141+
- ⏳ Verify no regressions
142+
- ⏳ Document improvements
143+
144+
## Success Criteria
145+
146+
- [ ] Lighthouse Performance ≥ 90
147+
- [ ] Bundle size reduction ≥ 20%
148+
- [ ] Zero performance regressions
149+
- [ ] All tests passing
150+
151+
## Related Files
152+
153+
- reports/2025-12-01-bundle-analysis.json
154+
- docs/PERFORMANCE.md
155+
- webpack.config.js
156+
```
157+
158+
---
159+
160+
**Last Updated:** December 9, 2025
161+
**Version:** 1.0.0

‎.github/schemas/README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Schemas Directory
2+
3+
This directory contains JSON schemas and configuration templates used for code generation, validation, and documentation.
4+
5+
## Files
6+
7+
### theme-config.schema.json
8+
9+
**Purpose:** Official JSON Schema defining all valid configuration options for theme generation.
10+
11+
**Usage:**
12+
- Defines the structure and validation rules for theme configuration files
13+
- Used by theme generators to validate user input
14+
- Referenced by editors and IDEs for autocomplete and validation
15+
- Provides documentation for all available configuration options
16+
17+
**Schema Defines:**
18+
- Required fields (theme_slug, theme_name, author)
19+
- Optional fields (description, version, license, etc.)
20+
- Design system tokens (colors, typography, spacing)
21+
- Theme structure settings
22+
- Feature flags
23+
- Content options
24+
25+
**Example:**
26+
```bash
27+
# Validate a configuration file against the schema
28+
jq -f .github/schemas/theme-config.schema.json my-config.json
29+
```
30+
31+
### theme-config.example.json
32+
33+
**Purpose:** Pre-filled example configuration showing realistic values for all schema fields.
34+
35+
**Usage:**
36+
- Template for users creating new theme configurations
37+
- Reference implementation of all available options
38+
- Documentation through working example
39+
- Copy and customize for new projects
40+
41+
**Content:**
42+
- Complete theme-config with all sections populated
43+
- Realistic values for Tour Operator theme
44+
- Comments explaining each major section
45+
- Valid against theme-config.schema.json
46+
47+
**Example:**
48+
```bash
49+
# Copy example to create your own configuration
50+
cp .github/schemas/theme-config.example.json my-theme-config.json
51+
52+
# Edit and customize for your theme
53+
vim my-theme-config.json
54+
55+
# Generate theme with custom config
56+
node bin/generate-theme.js --config my-theme-config.json
57+
```
58+
59+
## Adding New Schemas
60+
61+
When adding new schemas:
62+
63+
1. Create descriptive filename: `{domain}-{type}.schema.json`
64+
2. Follow JSON Schema standards
65+
3. Include comprehensive descriptions for all fields
66+
4. Add example files when appropriate
67+
5. Document in this README
68+
6. Reference schema in build scripts or generation tools
69+
70+
## Related Files
71+
72+
- [FILE_ORGANIZATION.md](../FILE_ORGANIZATION.md) - Overall file organization guide
73+
- [bin/generate-theme.js](../../bin/generate-theme.js) - Theme generation script
74+
- [.github/instructions/generate-theme.instructions.md](../instructions/generate-theme.instructions.md) - Theme generation guidance
75+
- [docs/THEME_STRUCTURE.md](../../docs/THEME_STRUCTURE.md) - Theme structure documentation

0 commit comments

Comments
 (0)