specweave 0.17.13 → 0.17.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +456 -0
- package/README.md +38 -1
- package/dist/src/cli/commands/cicd-monitor.d.ts +11 -0
- package/dist/src/cli/commands/cicd-monitor.d.ts.map +1 -0
- package/dist/src/cli/commands/cicd-monitor.js +154 -0
- package/dist/src/cli/commands/cicd-monitor.js.map +1 -0
- package/dist/src/cli/commands/validate-parent-repo.d.ts +8 -0
- package/dist/src/cli/commands/validate-parent-repo.d.ts.map +1 -0
- package/dist/src/cli/commands/validate-parent-repo.js +15 -0
- package/dist/src/cli/commands/validate-parent-repo.js.map +1 -0
- package/dist/src/cli/helpers/issue-tracker/types.d.ts +5 -0
- package/dist/src/cli/helpers/issue-tracker/types.d.ts.map +1 -1
- package/dist/src/cli/helpers/issue-tracker/types.js.map +1 -1
- package/dist/src/core/cicd/config-loader.d.ts +21 -0
- package/dist/src/core/cicd/config-loader.d.ts.map +1 -0
- package/dist/src/core/cicd/config-loader.js +190 -0
- package/dist/src/core/cicd/config-loader.js.map +1 -0
- package/dist/src/core/cicd/index.d.ts +12 -0
- package/dist/src/core/cicd/index.d.ts.map +1 -0
- package/dist/src/core/cicd/index.js +18 -0
- package/dist/src/core/cicd/index.js.map +1 -0
- package/dist/src/core/cicd/monitor-service.d.ts +92 -0
- package/dist/src/core/cicd/monitor-service.d.ts.map +1 -0
- package/dist/src/core/cicd/monitor-service.js +132 -0
- package/dist/src/core/cicd/monitor-service.js.map +1 -0
- package/dist/src/core/cicd/notifier.d.ts +102 -0
- package/dist/src/core/cicd/notifier.d.ts.map +1 -0
- package/dist/src/core/cicd/notifier.js +184 -0
- package/dist/src/core/cicd/notifier.js.map +1 -0
- package/dist/src/core/cicd/parent-repo-validator.d.ts +42 -0
- package/dist/src/core/cicd/parent-repo-validator.d.ts.map +1 -0
- package/dist/src/core/cicd/parent-repo-validator.js +201 -0
- package/dist/src/core/cicd/parent-repo-validator.js.map +1 -0
- package/dist/src/core/cicd/state-manager.d.ts +79 -0
- package/dist/src/core/cicd/state-manager.d.ts.map +1 -0
- package/dist/src/core/cicd/state-manager.js +197 -0
- package/dist/src/core/cicd/state-manager.js.map +1 -0
- package/dist/src/core/cicd/types.d.ts +119 -0
- package/dist/src/core/cicd/types.d.ts.map +1 -0
- package/dist/src/core/cicd/types.js +18 -0
- package/dist/src/core/cicd/types.js.map +1 -0
- package/dist/src/core/cicd/workflow-monitor.d.ts +98 -0
- package/dist/src/core/cicd/workflow-monitor.d.ts.map +1 -0
- package/dist/src/core/cicd/workflow-monitor.js +215 -0
- package/dist/src/core/cicd/workflow-monitor.js.map +1 -0
- package/dist/src/core/spec-content-sync.d.ts.map +1 -1
- package/dist/src/core/spec-content-sync.js +14 -6
- package/dist/src/core/spec-content-sync.js.map +1 -1
- package/package.json +2 -2
- package/plugins/specweave/agents/pm/AGENT.md +170 -2
- package/plugins/specweave/hooks/post-increment-planning.sh +89 -26
- package/plugins/specweave/hooks/user-prompt-submit.sh +4 -4
- package/plugins/specweave/skills/increment-planner/SKILL.md +15 -10
- package/plugins/specweave-ado/lib/ado-project-detector.js +32 -5
- package/plugins/specweave-ado/lib/ado-project-detector.ts +44 -5
- package/src/templates/AGENTS.md.template +55 -1
- package/src/templates/CLAUDE.md.template +51 -1
package/CLAUDE.md
CHANGED
|
@@ -1720,6 +1720,359 @@ SPEC-002: Intelligent AI Capabilities (Living Docs - Permanent, Feature-Level)
|
|
|
1720
1720
|
|
|
1721
1721
|
---
|
|
1722
1722
|
|
|
1723
|
+
## Enterprise Specs Organization (Domain-Based)
|
|
1724
|
+
|
|
1725
|
+
**NEW in v0.20.0**: Living docs specs organized by feature domain with rich metadata and auto-generated indices.
|
|
1726
|
+
|
|
1727
|
+
### The Problem with Flat Structure
|
|
1728
|
+
|
|
1729
|
+
**Before** (v0.19.x and earlier):
|
|
1730
|
+
```
|
|
1731
|
+
.specweave/docs/internal/specs/default/
|
|
1732
|
+
├── spec-001-core-framework-architecture.md
|
|
1733
|
+
├── spec-002-intelligent-capabilities.md
|
|
1734
|
+
├── spec-003-developer-experience.md
|
|
1735
|
+
... (30+ files in one folder)
|
|
1736
|
+
├── nfr-risks.md
|
|
1737
|
+
├── nfr-configuration-example.md
|
|
1738
|
+
├── overview-overview.md
|
|
1739
|
+
└── us-us1-single-provider-setup.md
|
|
1740
|
+
```
|
|
1741
|
+
|
|
1742
|
+
**Problems**:
|
|
1743
|
+
- ❌ 30+ files in single folder (hard to navigate)
|
|
1744
|
+
- ❌ Mixed document types (specs, NFRs, overviews, user stories)
|
|
1745
|
+
- ❌ No categorization by feature area
|
|
1746
|
+
- ❌ Poor scalability (becomes unmanageable at 100+ specs)
|
|
1747
|
+
- ❌ No rich metadata (status, priority, ownership)
|
|
1748
|
+
|
|
1749
|
+
### Enterprise Solution: Domain-Based Organization
|
|
1750
|
+
|
|
1751
|
+
**After** (v0.20.0+):
|
|
1752
|
+
```
|
|
1753
|
+
.specweave/docs/internal/specs/default/
|
|
1754
|
+
├── core-framework/ # Domain folder
|
|
1755
|
+
│ ├── README.md # Domain overview
|
|
1756
|
+
│ ├── spec-001-*.md # Feature specs
|
|
1757
|
+
│ ├── spec-004-*.md
|
|
1758
|
+
│ ├── nfrs/ # NFRs for this domain
|
|
1759
|
+
│ │ └── nfr-cross-platform.md
|
|
1760
|
+
│ └── user-stories/ # Extracted user stories
|
|
1761
|
+
│ └── us-001-*.md
|
|
1762
|
+
│
|
|
1763
|
+
├── developer-experience/
|
|
1764
|
+
│ ├── spec-003-*.md
|
|
1765
|
+
│ ├── spec-022-*.md
|
|
1766
|
+
│ └── user-stories/
|
|
1767
|
+
│
|
|
1768
|
+
├── integrations/
|
|
1769
|
+
│ ├── github/
|
|
1770
|
+
│ │ └── spec-017-sync-fix.md
|
|
1771
|
+
│ ├── jira/
|
|
1772
|
+
│ └── ado/
|
|
1773
|
+
│
|
|
1774
|
+
├── infrastructure/
|
|
1775
|
+
│ ├── spec-004-metrics.md
|
|
1776
|
+
│ ├── spec-029-cicd-failure.md
|
|
1777
|
+
│ └── nfrs/
|
|
1778
|
+
│
|
|
1779
|
+
├── quality-velocity/
|
|
1780
|
+
│ ├── spec-005-stabilization.md
|
|
1781
|
+
│ └── spec-010-dora-metrics.md
|
|
1782
|
+
│
|
|
1783
|
+
├── intelligence/
|
|
1784
|
+
│ ├── spec-002-intelligent-capabilities.md
|
|
1785
|
+
│ ├── spec-016-self-reflection.md
|
|
1786
|
+
│ └── spec-009-intelligent-reopen.md
|
|
1787
|
+
│
|
|
1788
|
+
└── _index/ # Auto-generated indices
|
|
1789
|
+
├── README.md # Master index
|
|
1790
|
+
├── by-status.md # Active, planning, completed, archived
|
|
1791
|
+
├── by-domain.md # All domains
|
|
1792
|
+
├── by-release.md # 1.0.0, 1.1.0, 2.0.0
|
|
1793
|
+
├── by-priority.md # P0, P1, P2, P3
|
|
1794
|
+
└── by-team.md # Core Team, Platform Team, etc.
|
|
1795
|
+
```
|
|
1796
|
+
|
|
1797
|
+
### Six Feature Domains
|
|
1798
|
+
|
|
1799
|
+
| Domain | Description | Examples |
|
|
1800
|
+
|--------|-------------|----------|
|
|
1801
|
+
| **core-framework** | Core framework capabilities | CLI, plugin architecture, configuration, lifecycle |
|
|
1802
|
+
| **developer-experience** | DX improvements | Setup, onboarding, docs, error messages, usability |
|
|
1803
|
+
| **integrations** | External tool integrations | GitHub, JIRA, Azure DevOps, Figma, Slack |
|
|
1804
|
+
| **infrastructure** | Platform, DevOps, ops | CI/CD, monitoring, observability, performance |
|
|
1805
|
+
| **quality-velocity** | Testing, metrics, releases | Testing framework, DORA metrics, stabilization |
|
|
1806
|
+
| **intelligence** | AI-powered features | Model selection, self-reflection, smart workflows |
|
|
1807
|
+
|
|
1808
|
+
### Rich Metadata for Every Spec
|
|
1809
|
+
|
|
1810
|
+
Every spec gets YAML frontmatter with comprehensive metadata:
|
|
1811
|
+
|
|
1812
|
+
```yaml
|
|
1813
|
+
---
|
|
1814
|
+
# Identity
|
|
1815
|
+
id: spec-001-core-framework-architecture
|
|
1816
|
+
title: "Core Framework & Architecture"
|
|
1817
|
+
version: 2.0
|
|
1818
|
+
status: active | planning | completed | archived
|
|
1819
|
+
|
|
1820
|
+
# Classification
|
|
1821
|
+
domain: core-framework
|
|
1822
|
+
category: feature | nfr | user-story | overview
|
|
1823
|
+
priority: P0 | P1 | P2 | P3
|
|
1824
|
+
complexity: low | medium | high | very-high
|
|
1825
|
+
|
|
1826
|
+
# Ownership
|
|
1827
|
+
team: Core Team
|
|
1828
|
+
owner: @anton-abyzov
|
|
1829
|
+
stakeholders: ["Product", "Engineering"]
|
|
1830
|
+
|
|
1831
|
+
# Lifecycle
|
|
1832
|
+
created: 2025-01-15
|
|
1833
|
+
last_updated: 2025-11-10
|
|
1834
|
+
target_release: 1.0.0
|
|
1835
|
+
|
|
1836
|
+
# Relationships
|
|
1837
|
+
increments: [0001, 0002, 0004, 0005]
|
|
1838
|
+
depends_on: []
|
|
1839
|
+
blocks: [spec-002, spec-003]
|
|
1840
|
+
related: [spec-016]
|
|
1841
|
+
|
|
1842
|
+
# External Links
|
|
1843
|
+
github_project: https://github.com/anton-abyzov/specweave/projects/1
|
|
1844
|
+
jira_epic: null
|
|
1845
|
+
confluence: null
|
|
1846
|
+
|
|
1847
|
+
# Tags
|
|
1848
|
+
tags: [framework, cli, plugin-system, mvp]
|
|
1849
|
+
|
|
1850
|
+
# Metrics
|
|
1851
|
+
estimated_effort: 120h
|
|
1852
|
+
actual_effort: 95h
|
|
1853
|
+
user_stories: 35
|
|
1854
|
+
completion: 100%
|
|
1855
|
+
---
|
|
1856
|
+
```
|
|
1857
|
+
|
|
1858
|
+
### Auto-Generated Navigation Indices
|
|
1859
|
+
|
|
1860
|
+
**Five index views** for different navigation needs:
|
|
1861
|
+
|
|
1862
|
+
1. **by-status.md** - Status-based view
|
|
1863
|
+
- Active (currently being worked on)
|
|
1864
|
+
- Planning (being planned)
|
|
1865
|
+
- Completed (delivered to production)
|
|
1866
|
+
- Archived (historical reference)
|
|
1867
|
+
|
|
1868
|
+
2. **by-domain.md** - Domain-based view
|
|
1869
|
+
- Core Framework (5 specs)
|
|
1870
|
+
- Developer Experience (3 specs)
|
|
1871
|
+
- Integrations (4 specs)
|
|
1872
|
+
- Infrastructure (3 specs)
|
|
1873
|
+
- Quality & Velocity (2 specs)
|
|
1874
|
+
- Intelligence (3 specs)
|
|
1875
|
+
|
|
1876
|
+
3. **by-release.md** - Release planning view
|
|
1877
|
+
- 1.0.0 (MVP release)
|
|
1878
|
+
- 1.1.0 (Post-launch improvements)
|
|
1879
|
+
- 2.0.0 (Major features)
|
|
1880
|
+
- Unscheduled (backlog)
|
|
1881
|
+
|
|
1882
|
+
4. **by-priority.md** - Priority-based view
|
|
1883
|
+
- P0 (Critical, security, production blockers)
|
|
1884
|
+
- P1 (High, MVPessential, core features)
|
|
1885
|
+
- P2 (Medium, nice-to-have, enhancements)
|
|
1886
|
+
- P3 (Low, future, backlog, deferred)
|
|
1887
|
+
|
|
1888
|
+
5. **by-team.md** - Team ownership view
|
|
1889
|
+
- Core Team
|
|
1890
|
+
- Platform Team
|
|
1891
|
+
- DX Team
|
|
1892
|
+
- Integrations Team
|
|
1893
|
+
|
|
1894
|
+
### Automated Classification
|
|
1895
|
+
|
|
1896
|
+
**Intelligent Living Docs Sync** auto-classifies specs by domain using keyword matching:
|
|
1897
|
+
|
|
1898
|
+
```typescript
|
|
1899
|
+
// Auto-classification during living docs sync
|
|
1900
|
+
const classifyDomain = (spec: string): string => {
|
|
1901
|
+
const keywords = {
|
|
1902
|
+
'core-framework': ['framework', 'cli', 'plugin', 'core', 'foundation'],
|
|
1903
|
+
'developer-experience': ['dx', 'ux', 'installation', 'setup', 'guide'],
|
|
1904
|
+
'integrations': ['github', 'jira', 'ado', 'figma', 'sync'],
|
|
1905
|
+
'infrastructure': ['cicd', 'monitoring', 'observability', 'performance'],
|
|
1906
|
+
'quality-velocity': ['testing', 'dora', 'metrics', 'stabilization'],
|
|
1907
|
+
'intelligence': ['ai', 'intelligent', 'smart', 'reflection', 'model']
|
|
1908
|
+
};
|
|
1909
|
+
|
|
1910
|
+
// Score each domain and return highest
|
|
1911
|
+
// Confidence threshold: 0.5 (50% keyword match)
|
|
1912
|
+
};
|
|
1913
|
+
```
|
|
1914
|
+
|
|
1915
|
+
### PM Agent Instructions
|
|
1916
|
+
|
|
1917
|
+
**CRITICAL**: When creating living docs specs, PM agent MUST:
|
|
1918
|
+
|
|
1919
|
+
1. **Classify Domain** - Determine feature domain based on content
|
|
1920
|
+
2. **Add Rich Metadata** - Include all required frontmatter fields
|
|
1921
|
+
3. **Use Correct Path** - Save to domain-specific folder
|
|
1922
|
+
4. **Generate README** - Update domain README.md
|
|
1923
|
+
5. **Regenerate Indices** - Run index generation after creating spec
|
|
1924
|
+
|
|
1925
|
+
**Example PM Agent Workflow**:
|
|
1926
|
+
|
|
1927
|
+
```typescript
|
|
1928
|
+
// Step 1: Classify domain
|
|
1929
|
+
const domain = classifyDomain(spec.title, spec.content);
|
|
1930
|
+
// Result: "core-framework"
|
|
1931
|
+
|
|
1932
|
+
// Step 2: Determine path
|
|
1933
|
+
const specPath = `.specweave/docs/internal/specs/default/${domain}/spec-001-core-framework.md`;
|
|
1934
|
+
|
|
1935
|
+
// Step 3: Add frontmatter
|
|
1936
|
+
const frontmatter = {
|
|
1937
|
+
id: 'spec-001-core-framework-architecture',
|
|
1938
|
+
title: 'Core Framework & Architecture',
|
|
1939
|
+
domain: 'core-framework',
|
|
1940
|
+
category: 'feature',
|
|
1941
|
+
priority: 'P1',
|
|
1942
|
+
status: 'active',
|
|
1943
|
+
team: 'Core Team',
|
|
1944
|
+
owner: '@anton-abyzov',
|
|
1945
|
+
created: '2025-11-12',
|
|
1946
|
+
target_release: '1.0.0',
|
|
1947
|
+
tags: ['framework', 'cli', 'plugin']
|
|
1948
|
+
};
|
|
1949
|
+
|
|
1950
|
+
// Step 4: Write spec with frontmatter
|
|
1951
|
+
writeSpec(specPath, frontmatter, content);
|
|
1952
|
+
|
|
1953
|
+
// Step 5: Update domain README
|
|
1954
|
+
updateDomainReadme(domain, spec);
|
|
1955
|
+
|
|
1956
|
+
// Step 6: Regenerate indices
|
|
1957
|
+
regenerateIndices();
|
|
1958
|
+
```
|
|
1959
|
+
|
|
1960
|
+
### Migration Scripts
|
|
1961
|
+
|
|
1962
|
+
**Three scripts for migration**:
|
|
1963
|
+
|
|
1964
|
+
1. **Classify Specs** (`scripts/classify-specs.ts`)
|
|
1965
|
+
- Scans existing specs
|
|
1966
|
+
- Auto-classifies by domain (keyword matching)
|
|
1967
|
+
- Generates classification report
|
|
1968
|
+
- Saves classification.json for migration
|
|
1969
|
+
|
|
1970
|
+
2. **Migrate to Domains** (`scripts/migrate-specs-to-domains.ts`)
|
|
1971
|
+
- Reads classification.json
|
|
1972
|
+
- Creates domain folders
|
|
1973
|
+
- Moves specs to domain-specific folders
|
|
1974
|
+
- Adds/updates frontmatter
|
|
1975
|
+
- Creates domain READMEs
|
|
1976
|
+
- Supports --dry-run mode
|
|
1977
|
+
|
|
1978
|
+
3. **Generate Indices** (`scripts/generate-spec-indices.ts`)
|
|
1979
|
+
- Scans all specs
|
|
1980
|
+
- Generates 5 navigation indices
|
|
1981
|
+
- Creates master index (README.md)
|
|
1982
|
+
- Shows statistics
|
|
1983
|
+
|
|
1984
|
+
**Usage**:
|
|
1985
|
+
|
|
1986
|
+
```bash
|
|
1987
|
+
# Step 1: Classify existing specs
|
|
1988
|
+
npx ts-node scripts/classify-specs.ts
|
|
1989
|
+
# Output: classification-report.md, classification.json
|
|
1990
|
+
|
|
1991
|
+
# Step 2: Review classification
|
|
1992
|
+
vim .specweave/docs/internal/specs/default/_index/classification-report.md
|
|
1993
|
+
|
|
1994
|
+
# Step 3: Migrate (dry-run first)
|
|
1995
|
+
npx ts-node scripts/migrate-specs-to-domains.ts --dry-run
|
|
1996
|
+
|
|
1997
|
+
# Step 4: Migrate (actual)
|
|
1998
|
+
npx ts-node scripts/migrate-specs-to-domains.ts
|
|
1999
|
+
|
|
2000
|
+
# Step 5: Generate indices
|
|
2001
|
+
npx ts-node scripts/generate-spec-indices.ts
|
|
2002
|
+
```
|
|
2003
|
+
|
|
2004
|
+
### Benefits
|
|
2005
|
+
|
|
2006
|
+
**For Users**:
|
|
2007
|
+
- ✅ Find specs 10x faster (browse by domain vs scroll through 30+ files)
|
|
2008
|
+
- ✅ Clear relationships (dependencies, blockers, related specs)
|
|
2009
|
+
- ✅ Rich metadata (status, priority, ownership, effort)
|
|
2010
|
+
- ✅ Multi-dimensional navigation (status, domain, release, team, priority)
|
|
2011
|
+
|
|
2012
|
+
**For Teams**:
|
|
2013
|
+
- ✅ Team ownership (core-team/, platform-team/)
|
|
2014
|
+
- ✅ Release planning (1.0.0, 1.1.0, 2.0.0)
|
|
2015
|
+
- ✅ Dependency management (blocks[], depends_on[])
|
|
2016
|
+
- ✅ Effort tracking (estimated_effort vs actual_effort)
|
|
2017
|
+
|
|
2018
|
+
**For Enterprise**:
|
|
2019
|
+
- ✅ Scalability (handles 100+ specs easily)
|
|
2020
|
+
- ✅ Compliance (audit trail via metadata)
|
|
2021
|
+
- ✅ Reporting (auto-generated indices for stakeholders)
|
|
2022
|
+
- ✅ Multi-project (backend/, frontend/, mobile/)
|
|
2023
|
+
|
|
2024
|
+
### Configuration
|
|
2025
|
+
|
|
2026
|
+
Add to `.specweave/config.json`:
|
|
2027
|
+
|
|
2028
|
+
```json
|
|
2029
|
+
{
|
|
2030
|
+
"specs": {
|
|
2031
|
+
"organization": {
|
|
2032
|
+
"strategy": "domain-based",
|
|
2033
|
+
"autoDomainClassification": true,
|
|
2034
|
+
"autoGenerateIndices": true,
|
|
2035
|
+
"requireMetadata": true,
|
|
2036
|
+
"domains": [
|
|
2037
|
+
"core-framework",
|
|
2038
|
+
"developer-experience",
|
|
2039
|
+
"integrations",
|
|
2040
|
+
"infrastructure",
|
|
2041
|
+
"quality-velocity",
|
|
2042
|
+
"intelligence"
|
|
2043
|
+
],
|
|
2044
|
+
"metadata": {
|
|
2045
|
+
"required": ["id", "title", "status", "domain", "team", "owner"],
|
|
2046
|
+
"optional": ["priority", "complexity", "tags", "increments"]
|
|
2047
|
+
}
|
|
2048
|
+
}
|
|
2049
|
+
}
|
|
2050
|
+
}
|
|
2051
|
+
```
|
|
2052
|
+
|
|
2053
|
+
### For Agents and Skills
|
|
2054
|
+
|
|
2055
|
+
**PM Agent MUST**:
|
|
2056
|
+
1. Always classify domain before creating spec
|
|
2057
|
+
2. Add rich frontmatter with all required fields
|
|
2058
|
+
3. Save to correct domain folder (not flat structure)
|
|
2059
|
+
4. Update domain README after creating spec
|
|
2060
|
+
5. Regenerate indices after spec creation
|
|
2061
|
+
|
|
2062
|
+
**Living Docs Sync MUST**:
|
|
2063
|
+
1. Detect domain from increment spec content
|
|
2064
|
+
2. Place spec in correct domain folder
|
|
2065
|
+
3. Add/update frontmatter with metadata
|
|
2066
|
+
4. Preserve existing classification if present
|
|
2067
|
+
5. Regenerate indices after sync
|
|
2068
|
+
|
|
2069
|
+
**See**:
|
|
2070
|
+
- [Organization Strategy](.specweave/docs/internal/specs/ORGANIZATION-STRATEGY.md) - Complete architecture
|
|
2071
|
+
- Migration scripts in `scripts/` directory
|
|
2072
|
+
- Configuration in `.specweave/config.json`
|
|
2073
|
+
|
|
2074
|
+
---
|
|
2075
|
+
|
|
1723
2076
|
## Living Completion Reports
|
|
1724
2077
|
|
|
1725
2078
|
### The Problem with Traditional Reports
|
|
@@ -2558,6 +2911,109 @@ cat .specweave/increments/0016-self-reflection-system/metadata.json
|
|
|
2558
2911
|
|
|
2559
2912
|
---
|
|
2560
2913
|
|
|
2914
|
+
**✅ Metadata Validation & Fallback Creation** (NEW in v0.14.0+):
|
|
2915
|
+
|
|
2916
|
+
**The Problem**: Hook failures (no GitHub CLI, network issues, permission problems) left increments without metadata.json, breaking status line, WIP limits, and external sync.
|
|
2917
|
+
|
|
2918
|
+
**The Solution**: Multi-layer validation ensures 100% metadata.json coverage.
|
|
2919
|
+
|
|
2920
|
+
**How It Works**:
|
|
2921
|
+
|
|
2922
|
+
**Layer 1: Hook Fallback** (Automatic)
|
|
2923
|
+
- After GitHub issue creation (success or fail)
|
|
2924
|
+
- Hook validates metadata.json exists
|
|
2925
|
+
- If missing → creates minimal metadata automatically
|
|
2926
|
+
- User sees warning + manual fix instructions
|
|
2927
|
+
|
|
2928
|
+
```bash
|
|
2929
|
+
# Hook output example (GitHub CLI not found):
|
|
2930
|
+
🔗 Checking GitHub issue auto-creation...
|
|
2931
|
+
⚠️ GitHub CLI (gh) not found, skipping issue creation
|
|
2932
|
+
|
|
2933
|
+
🔍 Validating metadata.json existence...
|
|
2934
|
+
⚠️ metadata.json not found (hook may have failed)
|
|
2935
|
+
📝 Creating minimal metadata as fallback...
|
|
2936
|
+
✅ Created minimal metadata.json
|
|
2937
|
+
⚠️ Note: No GitHub issue linked
|
|
2938
|
+
💡 Run /specweave-github:create-issue 0023-feature to create one manually
|
|
2939
|
+
```
|
|
2940
|
+
|
|
2941
|
+
**Layer 2: PM Agent Validation** (Automatic)
|
|
2942
|
+
- PM agent checks metadata.json after creating spec/plan/tasks
|
|
2943
|
+
- If missing → creates minimal metadata + warns user
|
|
2944
|
+
- Shows GitHub issue status (linked or not)
|
|
2945
|
+
|
|
2946
|
+
```markdown
|
|
2947
|
+
✅ Increment validation passed - metadata.json exists
|
|
2948
|
+
✅ GitHub issue #45 linked
|
|
2949
|
+
🔗 https://github.com/anton-abyzov/specweave/issues/45
|
|
2950
|
+
```
|
|
2951
|
+
|
|
2952
|
+
**Layer 3: Lazy Initialization** (Fallback)
|
|
2953
|
+
- `MetadataManager.read()` creates metadata on first access
|
|
2954
|
+
- Used by `/specweave:status`, `/pause`, `/resume` commands
|
|
2955
|
+
- Creates basic metadata but WITHOUT GitHub info
|
|
2956
|
+
|
|
2957
|
+
**Minimal Metadata Format** (when GitHub fails):
|
|
2958
|
+
```json
|
|
2959
|
+
{
|
|
2960
|
+
"id": "0023-release-management-enhancements",
|
|
2961
|
+
"status": "active",
|
|
2962
|
+
"type": "feature",
|
|
2963
|
+
"created": "2025-11-11T15:43:00Z",
|
|
2964
|
+
"lastActivity": "2025-11-11T15:43:00Z"
|
|
2965
|
+
}
|
|
2966
|
+
```
|
|
2967
|
+
|
|
2968
|
+
**Full Metadata Format** (when GitHub succeeds):
|
|
2969
|
+
```json
|
|
2970
|
+
{
|
|
2971
|
+
"id": "0016-self-reflection-system",
|
|
2972
|
+
"status": "active",
|
|
2973
|
+
"type": "feature",
|
|
2974
|
+
"created": "2025-11-10T12:00:00Z",
|
|
2975
|
+
"lastActivity": "2025-11-10T12:00:00Z",
|
|
2976
|
+
"github": {
|
|
2977
|
+
"issue": 30,
|
|
2978
|
+
"url": "https://github.com/anton-abyzov/specweave/issues/30",
|
|
2979
|
+
"synced": "2025-11-10T12:00:00Z"
|
|
2980
|
+
},
|
|
2981
|
+
"githubProfile": "specweave-dev"
|
|
2982
|
+
}
|
|
2983
|
+
```
|
|
2984
|
+
|
|
2985
|
+
**Benefits**:
|
|
2986
|
+
- ✅ **100% coverage**: Every increment gets metadata.json (no silent failures)
|
|
2987
|
+
- ✅ **Immediate feedback**: User knows if GitHub issue creation failed
|
|
2988
|
+
- ✅ **Graceful degradation**: Creates minimal metadata as fallback
|
|
2989
|
+
- ✅ **Clear next steps**: Shows manual fix command if needed
|
|
2990
|
+
- ✅ **Status line works**: Even without GitHub integration
|
|
2991
|
+
- ✅ **WIP limits work**: Counts active increments correctly
|
|
2992
|
+
|
|
2993
|
+
**Configuration Note**:
|
|
2994
|
+
|
|
2995
|
+
The old config key `hooks.post_increment_planning.auto_create_github_issue` is **deprecated** (v0.14.0+).
|
|
2996
|
+
|
|
2997
|
+
```json
|
|
2998
|
+
{
|
|
2999
|
+
"hooks": {
|
|
3000
|
+
"post_increment_planning": {
|
|
3001
|
+
// ❌ REMOVED (deprecated)
|
|
3002
|
+
// "auto_create_github_issue": false
|
|
3003
|
+
}
|
|
3004
|
+
},
|
|
3005
|
+
"sync": {
|
|
3006
|
+
"settings": {
|
|
3007
|
+
"autoCreateIssue": true // ✅ Use this instead
|
|
3008
|
+
}
|
|
3009
|
+
}
|
|
3010
|
+
}
|
|
3011
|
+
```
|
|
3012
|
+
|
|
3013
|
+
**Single source of truth**: `sync.settings.autoCreateIssue`
|
|
3014
|
+
|
|
3015
|
+
---
|
|
3016
|
+
|
|
2561
3017
|
## Status Line Feature (Increment Progress Display)
|
|
2562
3018
|
|
|
2563
3019
|
**NEW in v0.14.0**: Ultra-fast status line showing current increment progress with intelligent caching.
|
package/README.md
CHANGED
|
@@ -207,11 +207,12 @@ specweave init .
|
|
|
207
207
|
|
|
208
208
|
## Key Features
|
|
209
209
|
|
|
210
|
+
- 📚 **Living Documentation** - Auto-updates after every task (no manual sync!)
|
|
210
211
|
- 🧪 **Test-Aware Planning** - Embedded tests in BDD format (Given/When/Then)
|
|
211
212
|
- 🎯 **Disciplined Progress** - Can't start increment N+1 until N is DONE
|
|
212
213
|
- ⏸️ **Intelligent Pausing** - Auto-detects blockers, pauses with context, resumes when ready
|
|
213
|
-
- 📚 **Living Documentation** - Auto-updates after every task (no manual sync!)
|
|
214
214
|
- 🤖 **AI Agents** - PM, Architect, Quality Judge guide your work
|
|
215
|
+
- 🔧 **CI/CD Auto-Fix** - Workflow failures auto-fixed by Claude (just mention `@claude`)
|
|
215
216
|
- 🌍 **Multilingual** - Work in 11 languages (FREE translation)
|
|
216
217
|
- 🏢 **Multi-Project** - Organize by team/repo/microservice
|
|
217
218
|
- 🔗 **Issue Tracker Sync** - GitHub, Jira, Azure DevOps integration
|
|
@@ -220,6 +221,42 @@ specweave init .
|
|
|
220
221
|
|
|
221
222
|
---
|
|
222
223
|
|
|
224
|
+
## 🔧 CI/CD Auto-Fix
|
|
225
|
+
|
|
226
|
+
**Workflow fails? Claude fixes it automatically.**
|
|
227
|
+
|
|
228
|
+
When any GitHub Actions workflow fails, SpecWeave automatically:
|
|
229
|
+
1. Creates an issue mentioning `@claude`
|
|
230
|
+
2. Claude analyzes the failure logs
|
|
231
|
+
3. Claude creates a PR with the fix
|
|
232
|
+
4. You review and merge
|
|
233
|
+
5. Workflow re-runs and passes ✅
|
|
234
|
+
|
|
235
|
+
**Manual Trigger**:
|
|
236
|
+
```markdown
|
|
237
|
+
@claude This workflow failed: https://github.com/your-org/repo/actions/runs/12345
|
|
238
|
+
|
|
239
|
+
Please analyze the logs and create a fix PR.
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
**Automatic** (via GitHub Actions):
|
|
243
|
+
- Detects failures automatically
|
|
244
|
+
- No manual intervention needed
|
|
245
|
+
- Works 24/7 in the cloud
|
|
246
|
+
- Zero cost (uses GitHub Actions free tier)
|
|
247
|
+
|
|
248
|
+
**Common fixes**:
|
|
249
|
+
- TypeScript compilation errors
|
|
250
|
+
- Test failures
|
|
251
|
+
- Linting violations
|
|
252
|
+
- Missing imports
|
|
253
|
+
- Type mismatches
|
|
254
|
+
- Configuration issues
|
|
255
|
+
|
|
256
|
+
**[→ Setup Guide](https://spec-weave.com/docs/features/cicd-autofix)**
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
223
260
|
## 📖 Documentation
|
|
224
261
|
|
|
225
262
|
**Complete guides, tutorials, and API reference:**
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CI/CD Monitor CLI Command
|
|
3
|
+
*
|
|
4
|
+
* Command-line interface for starting/stopping/querying the CI/CD monitor.
|
|
5
|
+
*/
|
|
6
|
+
import { Command } from 'commander';
|
|
7
|
+
/**
|
|
8
|
+
* Register cicd-monitor command
|
|
9
|
+
*/
|
|
10
|
+
export declare function registerCICDMonitorCommand(program: Command): void;
|
|
11
|
+
//# sourceMappingURL=cicd-monitor.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cicd-monitor.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/cicd-monitor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkKpC;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0BjE"}
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CI/CD Monitor CLI Command
|
|
3
|
+
*
|
|
4
|
+
* Command-line interface for starting/stopping/querying the CI/CD monitor.
|
|
5
|
+
*/
|
|
6
|
+
import { WorkflowMonitor } from '../../core/cicd/workflow-monitor';
|
|
7
|
+
import { StateManager } from '../../core/cicd/state-manager';
|
|
8
|
+
import { Notifier } from '../../core/cicd/notifier';
|
|
9
|
+
import * as fs from 'fs-extra';
|
|
10
|
+
import * as path from 'path';
|
|
11
|
+
/**
|
|
12
|
+
* Load configuration from environment variables
|
|
13
|
+
*/
|
|
14
|
+
function loadConfig() {
|
|
15
|
+
return {
|
|
16
|
+
GITHUB_TOKEN: process.env.GITHUB_TOKEN,
|
|
17
|
+
GITHUB_OWNER: process.env.GITHUB_OWNER,
|
|
18
|
+
GITHUB_REPO: process.env.GITHUB_REPO,
|
|
19
|
+
CICD_POLL_INTERVAL: process.env.CICD_POLL_INTERVAL || '60000',
|
|
20
|
+
CICD_NOTIFICATION_CHANNELS: process.env.CICD_NOTIFICATION_CHANNELS || 'console,file',
|
|
21
|
+
CICD_WEBHOOK_URL: process.env.CICD_WEBHOOK_URL
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Start CI/CD monitor
|
|
26
|
+
*/
|
|
27
|
+
async function startMonitor(options) {
|
|
28
|
+
const config = loadConfig();
|
|
29
|
+
// Validate required config
|
|
30
|
+
if (!config.GITHUB_TOKEN) {
|
|
31
|
+
console.error('❌ Error: GITHUB_TOKEN environment variable is required');
|
|
32
|
+
console.error(' Set it in .env or export GITHUB_TOKEN=<your-token>');
|
|
33
|
+
process.exit(1);
|
|
34
|
+
}
|
|
35
|
+
if (!config.GITHUB_OWNER || !config.GITHUB_REPO) {
|
|
36
|
+
console.error('❌ Error: GITHUB_OWNER and GITHUB_REPO are required');
|
|
37
|
+
console.error(' Set them in .env or pass as arguments');
|
|
38
|
+
process.exit(1);
|
|
39
|
+
}
|
|
40
|
+
// Override from CLI arguments
|
|
41
|
+
const owner = options.owner || config.GITHUB_OWNER;
|
|
42
|
+
const repo = options.repo || config.GITHUB_REPO;
|
|
43
|
+
const pollInterval = parseInt(options.interval || config.CICD_POLL_INTERVAL, 10);
|
|
44
|
+
console.log('🚀 Starting CI/CD Monitor...');
|
|
45
|
+
console.log(` Repository: ${owner}/${repo}`);
|
|
46
|
+
console.log(` Poll interval: ${pollInterval}ms (${pollInterval / 1000}s)`);
|
|
47
|
+
// Create state manager
|
|
48
|
+
const stateManager = new StateManager();
|
|
49
|
+
// Create notifier
|
|
50
|
+
const notificationChannels = config.CICD_NOTIFICATION_CHANNELS.split(',').filter((c) => c.trim());
|
|
51
|
+
const notifier = new Notifier({
|
|
52
|
+
channels: notificationChannels,
|
|
53
|
+
webhookUrl: config.CICD_WEBHOOK_URL,
|
|
54
|
+
debug: options.debug || false
|
|
55
|
+
});
|
|
56
|
+
// Create and start monitor
|
|
57
|
+
const monitor = new WorkflowMonitor({
|
|
58
|
+
token: config.GITHUB_TOKEN,
|
|
59
|
+
owner,
|
|
60
|
+
repo,
|
|
61
|
+
pollInterval,
|
|
62
|
+
debug: options.debug || false
|
|
63
|
+
}, stateManager);
|
|
64
|
+
monitor.start();
|
|
65
|
+
console.log('✅ Monitor started');
|
|
66
|
+
console.log(' Press Ctrl+C to stop');
|
|
67
|
+
// Handle graceful shutdown
|
|
68
|
+
process.on('SIGINT', () => {
|
|
69
|
+
console.log('\n⏹️ Stopping monitor...');
|
|
70
|
+
monitor.stop();
|
|
71
|
+
console.log('✅ Monitor stopped');
|
|
72
|
+
process.exit(0);
|
|
73
|
+
});
|
|
74
|
+
// Keep process alive
|
|
75
|
+
await new Promise(() => { });
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Query monitor status
|
|
79
|
+
*/
|
|
80
|
+
async function queryStatus() {
|
|
81
|
+
const stateManager = new StateManager();
|
|
82
|
+
const state = await stateManager.loadState();
|
|
83
|
+
console.log('📊 CI/CD Monitor Status\n');
|
|
84
|
+
// Last poll
|
|
85
|
+
if (state.lastPoll) {
|
|
86
|
+
const lastPollDate = new Date(state.lastPoll);
|
|
87
|
+
const elapsed = Date.now() - lastPollDate.getTime();
|
|
88
|
+
console.log(` Last poll: ${lastPollDate.toLocaleString()} (${Math.floor(elapsed / 1000)}s ago)`);
|
|
89
|
+
}
|
|
90
|
+
else {
|
|
91
|
+
console.log(' Last poll: Never');
|
|
92
|
+
}
|
|
93
|
+
// Failure statistics
|
|
94
|
+
console.log(`\n📈 Statistics:`);
|
|
95
|
+
console.log(` Total failures detected: ${state.totalFailures}`);
|
|
96
|
+
console.log(` Failures processed: ${state.totalProcessed}`);
|
|
97
|
+
console.log(` Failures fixed: ${state.totalFixed}`);
|
|
98
|
+
// Unprocessed failures
|
|
99
|
+
const unprocessed = Object.values(state.failures).filter((f) => !f.processed);
|
|
100
|
+
console.log(`\n⏳ Unprocessed failures: ${unprocessed.length}`);
|
|
101
|
+
if (unprocessed.length > 0) {
|
|
102
|
+
console.log('\n Recent unprocessed failures:');
|
|
103
|
+
unprocessed.slice(0, 5).forEach((failure) => {
|
|
104
|
+
console.log(` • ${failure.workflowName} (run #${failure.runId})`);
|
|
105
|
+
console.log(` Branch: ${failure.branch}`);
|
|
106
|
+
console.log(` Detected: ${new Date(failure.detectedAt).toLocaleString()}`);
|
|
107
|
+
console.log(` URL: ${failure.url}\n`);
|
|
108
|
+
});
|
|
109
|
+
if (unprocessed.length > 5) {
|
|
110
|
+
console.log(` ... and ${unprocessed.length - 5} more`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Clear monitor state (reset)
|
|
116
|
+
*/
|
|
117
|
+
async function clearState() {
|
|
118
|
+
const statePath = path.join(process.cwd(), '.specweave/state/cicd-monitor.json');
|
|
119
|
+
if (await fs.pathExists(statePath)) {
|
|
120
|
+
await fs.remove(statePath);
|
|
121
|
+
console.log('✅ State cleared');
|
|
122
|
+
}
|
|
123
|
+
else {
|
|
124
|
+
console.log('ℹ️ No state to clear');
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Register cicd-monitor command
|
|
129
|
+
*/
|
|
130
|
+
export function registerCICDMonitorCommand(program) {
|
|
131
|
+
const monitorCmd = program
|
|
132
|
+
.command('cicd-monitor')
|
|
133
|
+
.description('CI/CD workflow monitoring and auto-fix');
|
|
134
|
+
// Start monitor
|
|
135
|
+
monitorCmd
|
|
136
|
+
.command('start')
|
|
137
|
+
.description('Start monitoring GitHub Actions workflows')
|
|
138
|
+
.option('-o, --owner <owner>', 'GitHub repository owner')
|
|
139
|
+
.option('-r, --repo <repo>', 'GitHub repository name')
|
|
140
|
+
.option('-i, --interval <ms>', 'Poll interval in milliseconds (default: 60000)')
|
|
141
|
+
.option('-d, --debug', 'Enable debug logging')
|
|
142
|
+
.action(startMonitor);
|
|
143
|
+
// Query status
|
|
144
|
+
monitorCmd
|
|
145
|
+
.command('status')
|
|
146
|
+
.description('Show monitor status and statistics')
|
|
147
|
+
.action(queryStatus);
|
|
148
|
+
// Clear state
|
|
149
|
+
monitorCmd
|
|
150
|
+
.command('clear')
|
|
151
|
+
.description('Clear monitor state (reset)')
|
|
152
|
+
.action(clearState);
|
|
153
|
+
}
|
|
154
|
+
//# sourceMappingURL=cicd-monitor.js.map
|