diff --git a/.gitignore b/.gitignore index 2fd67de..d23e25b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,7 @@ .artifacts/ TestResults/ *.log + +.tmp-gh-*.ps1 + +.tmp-venv*/ diff --git a/AGENTS.md b/AGENTS.md index 6110fe6..ae8541d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,118 +2,24 @@ ## Product Standard -CAS Workstation is a public, Windows-first enterprise bootstrap product for -AI-native developers. Changes must be safe, idempotent, testable, and suitable -for execution on a developer's primary workstation. - -## Engineering Rules - -- Never embed credentials, access tokens, or machine-specific secrets. -- Default destructive operations to dry-run or explicit confirmation. -- Keep installation state and generated configuration under the configured CAS - root and profile paths. -- Prefer declarative manifest data over hard-coded tool or repository lists. -- Validate manifest and doctor output against their JSON schemas. -- Add Pester tests for PowerShell behavior and failure paths. -- Preserve support for non-interactive CI validation. - -## Verification - -Run the strongest available checks before committing: - -```powershell -Invoke-Pester -.\doctor.ps1 -JsonPath .artifacts\doctor.json -``` - - -## Project - -**CAS Workstation** - -CAS Workstation is a public, Windows-first enterprise bootstrap product that turns a clean developer workstation into a complete, validated AI-native development environment for the Coding-Autopilot-System ecosystem. It provides a single trustworthy surface to install, operate, diagnose, upgrade, recover, and safely remove declaratively selected tools, repositories, services, skills, and AI client configuration. +CAS Workstation is a public, Windows-first enterprise bootstrap product for AI-native developers. Changes must be safe, idempotent, testable, and suitable for execution on a developer's primary workstation. **Core Value:** An AI developer can run one safe, repeatable workflow and receive a complete, working workstation without manually discovering or reconciling prerequisites. -### Constraints - -- **Platform**: Windows 11 and PowerShell 5.1+ are the supported v1 host contract — compatibility must be verified in CI and on clean machines. -- **Safety**: Destructive actions require explicit intent, CAS ownership evidence, and canonical path-boundary validation — primary workstations cannot tolerate unsafe cleanup. -- **Security**: No embedded credentials or tokens; downloads and package execution must be allowlisted, observable, and auditable — supply-chain trust is mandatory. -- **Configuration**: Declarative profile and manifest data is authoritative — tool, repository, service, client, workspace, and skill lists must not be hard-coded. -- **State**: CAS-managed state and generated configuration remain under configured CAS root/profile paths — unrelated user state must remain untouched. -- **Automation**: Interactive and non-interactive flows must expose equivalent behavior and machine-readable outcomes — CI and repeatable operations depend on it. -- **Quality**: Schemas, Pester tests, static analysis, and clean-machine journeys are release gates — documentation-only confidence is insufficient. - +### Modular Context Directory - -## Technology Stack +To save token limits, context rules are localized. Read the nearest `context.md` file before making changes: -## Recommended Baseline -| Area | Choice | Rationale | -|------|--------|-----------| -| Host automation | PowerShell 5.1-compatible modules and advanced scripts | Native Windows reach, supports interactive and unattended execution | -| Package sources | WinGet and Scoop adapters behind a common interface | Existing ecosystem fit while keeping source policy declarative | -| Test framework | Pester 5 with isolated filesystem/process seams | Standard PowerShell behavior, failure-path, and contract testing | -| Static quality | PSScriptAnalyzer plus strict mode | Catches common correctness and maintainability defects | -| Contracts | JSON Schema Draft 2020-12 | Existing doctor schema uses this version; extend to manifest, state, plan, and support bundle | -| State | Versioned JSON operation journal with atomic replacement | Transparent, portable, inspectable, and recoverable without a database | -| Logging | Structured JSON Lines plus concise console rendering | Human operations and machine diagnostics from the same events | -| CI | GitHub Actions on Windows and Ubuntu for schema/docs portability | Primary behavior on Windows; cross-platform contract checks where useful | -| Release | GitHub Releases, signed checksums, SBOM, SLSA provenance | Public verifiability and supply-chain evidence | -| E2E | Disposable Windows VM runner/sandbox image | Proves clean-machine installation and uninstall behavior | -## Compatibility Policy -- Keep Windows PowerShell 5.1 compatibility until the support matrix explicitly changes. -- Test PowerShell 7 as the preferred development shell. -- Pin minimum supported tool versions in the manifest, but resolve installers through allowlisted adapters. -- Keep WSL as an optional managed dependency, never the primary control plane. -## Avoid -- Embedding package-manager commands throughout orchestration logic. -- Treating command presence as proof that an installation is healthy. -- Writing directly to mutable JSON state without atomic replace and backup. -- Using local `stdio` MCP as the implied production architecture; document it as workstation-local only. -## Primary References -- Microsoft WinGet configuration: https://learn.microsoft.com/windows/package-manager/configuration/ -- PowerShell `SupportsShouldProcess`: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute -- Pester documentation: https://pester.dev/docs/introduction -- JSON Schema 2020-12: https://json-schema.org/draft/2020-12 -- SLSA provenance: https://slsa.dev/spec/ - +- **`scripts/context.md`**: Read for PowerShell automation rules, idempotency constraints, and safety guidelines. +- **`tests/context.md`**: Read for Pester testing framework, static quality, and verification requirements. +- **`schemas/context.md`**: Read for JSON schema contracts and declarative configuration rules. - -## Conventions +## Engineering Rules (Global Workstation Constraints) -Conventions not yet established. Will populate as patterns emerge during development. - - - -## Architecture - -Architecture not yet mapped. Follow existing patterns found in the codebase. - +- Never embed credentials, access tokens, or machine-specific secrets. +- Default destructive operations to dry-run or explicit confirmation. +- Validation: Schemas, Pester tests, static analysis, and clean-machine journeys are release gates. - ## Project Skills -No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/`, or `.codex/skills/` with a `SKILL.md` index file. - - - -## GSD Workflow Enforcement - -Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. - -Use these entry points: -- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks -- `/gsd-debug` for investigation and bug fixing -- `/gsd-execute-phase` for planned phase work - -Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. - - - -## Developer Profile - -> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile. -> This section is managed by `generate-claude-profile` -- do not edit manually. - +Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/`, or `.codex/skills/` with a `SKILL.md` index file. diff --git a/schemas/context.md b/schemas/context.md new file mode 100644 index 0000000..2f72da1 --- /dev/null +++ b/schemas/context.md @@ -0,0 +1,9 @@ +# Schema & Validation Context + +## Technology Stack +- **Contracts**: JSON Schema Draft 2020-12. Existing doctor schema uses this version; extend to manifest, state, plan, and support bundle. + +## Guidelines +- **Validation**: Validate manifest and doctor output against their JSON schemas. +- **Declarative Strategy**: Prefer declarative manifest data over hard-coded tool or repository lists. Tool, repository, service, client, workspace, and skill lists must not be hard-coded. +- **Reference**: JSON Schema 2020-12: https://json-schema.org/draft/2020-12 diff --git a/scripts/context.md b/scripts/context.md new file mode 100644 index 0000000..e994da1 --- /dev/null +++ b/scripts/context.md @@ -0,0 +1,11 @@ +# PowerShell Automation Context + +## Technology Stack +- **Host automation**: PowerShell 5.1-compatible modules and advanced scripts. Native Windows reach, supports interactive and unattended execution. +- **Package sources**: WinGet and Scoop adapters behind a common interface. + +## Guidelines +- **Idempotency**: Changes must be safe, idempotent, testable, and suitable for execution on a developer's primary workstation. +- **Security**: Never embed credentials, access tokens, or machine-specific secrets. Default destructive operations to dry-run or explicit confirmation. +- **State**: Keep installation state and generated configuration under the configured CAS root and profile paths. Versioned JSON operation journal with atomic replacement. +- **Avoid**: Embedding package-manager commands throughout orchestration logic. Treating command presence as proof that an installation is healthy. diff --git a/tests/context.md b/tests/context.md new file mode 100644 index 0000000..daaa7ca --- /dev/null +++ b/tests/context.md @@ -0,0 +1,13 @@ +# Testing Context + +## Technology Stack +- **Test framework**: Pester 5 with isolated filesystem/process seams. Standard PowerShell behavior, failure-path, and contract testing. +- **Static quality**: PSScriptAnalyzer plus strict mode. Catches common correctness and maintainability defects. +- **E2E**: Disposable Windows VM runner/sandbox image for proving clean-machine installation. + +## Verification +Run the strongest available checks before committing: +```powershell +Invoke-Pester +.\doctor.ps1 -JsonPath .artifacts\doctor.json +```