CodeSpec

Spec-driven development for Power Apps Code Apps.

Create Code Apps projects with OpenSpec, GitHub Copilot workflows, and reviewable requirements from the first commit.

---

CodeSpec is an open source initializer for teams building Power Apps Code Apps. It combines a customized Code Apps starter, OpenSpec project artifacts, and GitHub Copilot prompt and skill files so app development can move from idea to reviewed requirements to implementation without losing decisions in chat history.

The goal is practical spec-driven development for Code Apps. CodeSpec uses OpenSpec today because it is lightweight, file-based, and easy to learn. If a better spec-driven development framework emerges, CodeSpec should be able to adopt it while preserving the same developer experience.

Table Of Contents

• Quick Start
• Who CodeSpec Is For
• Why Spec-Driven Development
• What You Get
• Prerequisites
• What The CLI Does
• Generated Project
• OPSX Workflow
• Development Guidelines For Generated Apps
• CLI Options
• Contributing
• Repository Layout
• Maintaining The Starter
• Maintaining OpenSpec Assets
• Verification
• Publishing Checklist
• License

Quick Start

npm install -g @voyager163/codespec@latest
codespec init my-app
cd my-app
code .

During initialization, CodeSpec checks for the Power Platform CLI and guides you through pac code init. Before prompting for values, it asks you to find your Power Platform environment ID and app display name, then waits for Enter.

If macOS reports an EACCES permission error while installing globally, configure npm to use a user-writable global package folder, then retry the install:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g @voyager163/codespec@latest

To create a project without a global install, run:

npx @voyager163/codespec init my-app

To create the local project first and initialize Power Apps later, skip the guided PAC step:

codespec init my-app --skip-pac-init
cd my-app
pac code init --environment <environmentId> --displayName <appDisplayName>

The environment ID selects the target Power Platform environment. The display name is the friendly app name shown in Power Apps.

If you skipped initialization or declined the prompt, run the command later from the generated project folder:

pac code init --environment <environmentId> --displayName <appDisplayName>

Use the expanded OPSX workflow in GitHub Copilot to drive changes:

/opsx:explore
/opsx:new
/opsx:continue
/opsx:ff
/opsx:propose
/opsx:verify
/opsx:apply
/opsx:sync
/opsx:archive
/opsx:bulk-archive
/opsx:onboard

Start local development:

npm run dev

Who CodeSpec Is For

CodeSpec is for developers and teams who want to build Power Apps Code Apps with a repeatable, reviewable workflow:

• makers and developers starting a new Code Apps project;
• teams using GitHub Copilot for implementation but wanting durable requirements;
• maintainers who want app behavior captured in repository files rather than scattered chat transcripts;
• organizations evaluating spec-driven development for Power Platform work.

Why Spec-Driven Development

AI-assisted development works best when the project keeps its intent close to the code. CodeSpec encourages a loop where ideas become files that can be reviewed, changed, implemented, verified, and archived.

Explore the idea -> propose the change -> generate specs/design/tasks -> implement -> archive

OpenSpec keeps that loop lightweight:

• Fluid, not rigid.
• Iterative, not waterfall.
• Easy to start, but organized enough for real projects.
• Built around project files that can be reviewed, updated, and archived.

OpenSpec is the current framework choice, not an irreversible constraint. CodeSpec is about making spec-driven development practical for Code Apps; the framework can evolve if the ecosystem gives the project a better fit.

What You Get

A generated CodeSpec app includes:

• a Vite, React 19, and TypeScript Code Apps starter;
• Tailwind CSS, shadcn/ui components, theming, and Lucide icons;
• React Router, TanStack Query, TanStack Table, and Zustand;
• an OpenSpec configuration tailored for Power Apps Code Apps;
• GitHub Actions workflows for GHAS CodeQL, Dependency Review, quality checks, coverage, Semgrep OSS, npm audit, and OpenSSF Scorecard;
• all OPSX prompt files for GitHub Copilot under .github/prompts/;
• matching OpenSpec skill folders under .github/skills/;
• project-local guidance for exploration, proposal, implementation, verification, syncing, and archiving.

One repo setting must be enabled manually: go to Settings > Code security and turn on Secret Scanning and Push Protection. These are GHAS features but have no workflow file; GitHub runs them natively on every push.

Prerequisites

• Node.js 20.19.0 or newer
• npm
• git
• Power Platform CLI for guided pac code init, unless running with --skip-pac-init
• Visual Studio Code with GitHub Copilot
• OpenSpec

If OpenSpec is missing, the initializer installs it automatically:

npm install -g @fission-ai/openspec@latest

When CodeSpec runs OpenSpec on a developer's behalf, it sets OPENSPEC_TELEMETRY=0 for OpenSpec availability checks, automatic OpenSpec installation, and generated-project OpenSpec setup. Generated OPSX prompts and skills also instruct agents to use the same opt-out when they run OpenSpec CLI commands.

What The CLI Does

The initializer runs this setup flow:

1. Run through the `init` subcommand and ask for a project name if missing
2. Check Node.js
3. Check npm
4. Check git
5. Check the Power Platform CLI unless Power Apps initialization is skipped
6. Check OpenSpec and install it if missing
7. Fail if the target folder already exists
8. Copy templates/starter into the target folder
9. Copy the OPSX prompts and skills into .github/
10. Run npm install
11. Run openspec init or openspec update
12. Replace openspec/config.yaml with the fixed Code Apps config
13. Run git init
14. Guide `pac code init` unless skipped
15. Print next steps

The initializer prints setup progress as a grouped tree so completed, skipped, and failed steps are visible. It does not install the Power Platform CLI, authenticate to Power Platform, discover environments automatically, install Code Apps assistant plugins, register plugin marketplaces, or ask developers to choose an AI assistant.

Generated Project

Generated projects include:

my-app/
	package.json
	src/
	public/
	openspec/
		config.yaml
		changes/
		specs/
	.github/
		workflows/
			ghas.yml
			quality.yml
		prompts/
			opsx-*.prompt.md
		skills/
			openspec-*/

The generated openspec/config.yaml is tailored for Power Apps Code Apps:

Platform: Power Apps Code Apps
Frontend: Vite + React 19 TypeScript
Styling: Tailwind CSS
Routing: React Router
Data: TanStack Query + Power Platform connectors
Auth: Power Platform managed
Deploy: pac CLI

OPSX Workflow

Use the expanded OpenSpec workflow commands as the normal development path. Generated projects include all 11 OPSX prompt files and all 11 matching OpenSpec skill folders by default.

Generated OPSX workflow instructions require agents to run OpenSpec CLI commands with OPENSPEC_TELEMETRY=0 in the command environment.

Command	Purpose
/opsx:explore <idea>	Think through an idea without implementing. Use this for architecture exploration, problem framing, risks, and tradeoffs.
/opsx:new <change>	Start a new change and inspect the first artifact instructions before drafting.
/opsx:continue <change>	Continue creating or updating artifacts for an active change.
/opsx:ff <change>	Fast-forward artifact creation until the change is ready for implementation.
/opsx:propose <change>	Create a proposal, design, specs, and tasks for a new change.
/opsx:verify <change>	Check that the change artifacts are complete and internally consistent.
/opsx:apply <change>	Implement the tasks from an approved OpenSpec change.
/opsx:sync <change>	Sync completed change artifacts back into the canonical specs when appropriate.
/opsx:archive <change>	Archive a completed change and sync the final specs.
/opsx:bulk-archive	Archive multiple completed changes when the workspace has accumulated finished work.
/opsx:onboard	Inspect the project and generate onboarding context for the assistant.

Development Guidelines For Generated Apps

Follow these rules when building Code Apps from the generated project.

• Start meaningful work with /opsx:explore, /opsx:new, /opsx:ff, or /opsx:propose before implementation.
• Keep requirements in OpenSpec artifacts, not only in chat history.
• Use Power Platform connectors for runtime data access.
• Do not add a custom backend unless the OpenSpec change explicitly justifies it.
• Do not add a custom auth layer; authentication is handled by Power Platform.
• Use generated services under src/generated/ when Power Apps tooling creates connector services.
• Keep TypeScript strict and fix type errors before considering a task complete.
• Keep UI changes consistent with the starter's Vite, React, Tailwind, and routing conventions.
• Run build and verification commands before archiving a change.

CLI Options

codespec init my-app --skip-install
codespec init my-app --skip-git
codespec init my-app --skip-pac-init

By default, npm install, git init, and guided Power Apps initialization run automatically. Use --skip-pac-init to create the local project without checking for pac or running pac code init.

Project creation requires the explicit init subcommand. Running codespec my-app directly is rejected so root-level commands can remain unambiguous.

The CLI fails if the target folder already exists. This avoids accidental overwrites.

Contributing

CodeSpec is open source. Contributions are welcome around the starter template, OPSX workflow, OpenSpec configuration, verification coverage, docs, and future spec-driven development framework evaluation.

Please read CONTRIBUTING.md before opening a pull request. By participating in this project, you also agree to follow the Code of Conduct.

Repository Layout

This repository contains both the initializer and the templates it copies.

codespec/
	bin/
		create-codespec.js
	templates/
		starter/
			SOURCE.md
			package.json
			src/
			public/
		openspec/
			config.yaml
		github/
			prompts/
			skills/
	openspec/
		changes/
		specs/
	scripts/
		verify-generated-project.js

templates/starter was imported once from microsoft/PowerAppsCodeApps/templates/starter. This repo now owns that snapshot, so future starter changes should be made here intentionally.

Maintaining The Starter

When updating the starter template:

1. Edit files under templates/starter/.
2. Keep templates/starter/SOURCE.md accurate if you intentionally resync from upstream.
3. Make sure generated projects still build with npm run build.
4. Run the verification script in this repo.

Do not make the CLI fetch the Microsoft starter during project creation. The initializer should always use the local customized starter.

Maintaining OpenSpec Assets

The generated .github files come from templates/github.

If the repo's live OPSX prompts or skills are updated, sync the template copy as well:

rm -rf templates/github/prompts templates/github/skills
mkdir -p templates/github/prompts templates/github/skills
cp -R .github/prompts/. templates/github/prompts/
cp -R .github/skills/. templates/github/skills/

Generated projects should include ghas.yml and quality.yml workflow files, all 11 OPSX prompt files, and all 11 OpenSpec skill folders.

Updating OpenSpec

To update OpenSpec globally:

npm install -g @fission-ai/openspec@latest

Inside an existing generated project, refresh OpenSpec instructions with:

openspec update

This initializer overwrites openspec/config.yaml during creation so generated projects receive the Power Apps Code Apps defaults.

Verification

Run the smoke verification script:

npm run verify

The script creates a temporary generated project and checks that:

• the starter files are copied;
• OpenSpec initializes successfully;
• generated GHAS and quality workflow files are present;
• all 11 OPSX prompt files are present;
• all 11 OpenSpec skill folders are present;
• openspec/config.yaml matches the fixed Power Apps Code Apps config;
• generated project tooling includes React 19 guidance, Vitest, Playwright, Prettier, and Power Apps telemetry scaffolding.

Before publishing or handing off a change, also run:

node --check bin/create-codespec.js
node --check scripts/verify-generated-project.js
npm pack --dry-run

For starter template changes, also validate the starter itself:

cd templates/starter
npm install --no-package-lock
npm run build
npm run lint
npm run test:run
npm run format:check
npx playwright install
npm run e2e

For documentation or community-file changes, also review:

• README badge links and image paths;
• accessible alt text for media assets;
• links to CONTRIBUTING.md, CODE_OF_CONDUCT.md, and LICENSE;
• CodeSpec project identity terms;
• Power Apps Code Apps, pac code init, and microsoft/PowerAppsCodeApps references.

Publishing Checklist

Before publishing a package version:

1. Run npm run verify.
2. Run npm pack --dry-run and inspect the included files.
3. Confirm npm install -g @voyager163/codespec@latest installs the codespec command after publishing.
4. Confirm templates/starter contains no local secrets or generated build output.
5. Confirm templates/openspec/config.yaml has the desired Power Apps Code Apps defaults.
6. Confirm templates/github contains exactly the expected OPSX prompts and skills.
7. Confirm README badges, community links, and media assets render correctly.

License

MIT. The starter template snapshot is based on Microsoft's Power Apps Code Apps starter, which is also MIT licensed.