simplespec 0.1.0

package/.simplespec/examples/example-spec.md

@@ -0,0 +1,241 @@
+---
+name: User Authentication via OAuth2
+description: Enable users to authenticate using Google and GitHub OAuth2 providers
+metadata:
+  created_date: 2026-02-28
+  last_updated: 2026-02-28
+  author: Engineering Team
+  status: draft
+---
+
+# User Authentication via OAuth2
+
+## Summary
+This spec defines the implementation of OAuth2-based authentication for our application, allowing users to sign in using their Google or GitHub accounts. This eliminates the need for password management and reduces friction in the signup process, while improving security through trusted third-party authentication providers.
+
+## Goals
+- Enable users to sign up and log in using Google OAuth2
+- Enable users to sign up and log in using GitHub OAuth2  
+- Store essential user profile information (email, name, avatar URL) from OAuth providers
+- Maintain secure session management with proper token handling
+- Provide a seamless authentication experience with < 3 second flow completion
+
+## Non-goals
+- Single Sign-On (SSO) for enterprise accounts - will be addressed in future spec
+- Multi-factor authentication (MFA) - deferred to Q2 2026
+- Account linking (connecting multiple OAuth providers to one account) - future enhancement
+- Custom username/password authentication - we're moving away from this model
+- Social features using OAuth provider data (friends, followers, etc.)
+
+## Requirements
+
+### Functional Requirements
+- FR1: System must support login via Google OAuth2 with authorization code flow
+- FR2: System must support login via GitHub OAuth2 with authorization code flow
+- FR3: System must capture and store user email, display name, and avatar URL from OAuth provider
+- FR4: System must create a new user account on first OAuth login
+- FR5: System must maintain user sessions with secure, HTTP-only cookies
+- FR6: System must provide logout functionality that clears sessions and revokes tokens
+- FR7: System must display clear error messages for failed authentication attempts
+- FR8: System must redirect users to their intended destination after successful login
+
+### Non-functional Requirements
+- NFR1: OAuth authentication flow must complete within 3 seconds (95th percentile)
+- NFR2: Access tokens must be encrypted at rest using AES-256
+- NFR3: Session tokens must expire after 30 days of inactivity
+- NFR4: System must support 1000 concurrent authentication requests
+- NFR5: All authentication events must be logged for security audit
+- NFR6: OAuth redirect URIs must use HTTPS in production
+- NFR7: Implementation must comply with OAuth2 RFC 6749 standard
+
+## Dependencies
+- Google OAuth2 API (https://developers.google.com/identity/protocols/oauth2)
+- GitHub OAuth2 API (https://docs.github.com/en/apps/oauth-apps)
+- PostgreSQL database for user account storage
+- Redis for session storage and caching
+- Express.js middleware for request handling
+- Environment variables for OAuth client credentials (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET)
+- Related spec reference: `spec:12-user-profile-schema.md`
+
+## Proposed Approach
+
+### Options
+
+**Option 1: Use Passport.js with OAuth strategies**
+- Pros: 
+  - Well-established library with 500+ authentication strategies
+  - Extensive community support and documentation
+  - Handles edge cases and security best practices
+- Cons: 
+  - Heavyweight (~200KB minified)
+  - Includes many features we won't use
+  - Adds another dependency to maintain
+- Effort: 2 weeks
+
+**Option 2: Implement OAuth2 flow manually with axios**
+- Pros: 
+  - Full control over authentication flow
+  - Minimal dependencies
+  - Can optimize for our specific use case
+- Cons: 
+  - More code to write and maintain
+  - Higher security risk if implementation has bugs
+  - Need to handle all OAuth edge cases ourselves
+- Effort: 3-4 weeks
+
+**Option 3: Use NextAuth.js (or similar modern library)**
+- Pros:
+  - Modern, lightweight, designed for React/Next.js apps
+  - Built-in session management
+  - Good TypeScript support
+- Cons:
+  - Newer library, smaller community
+  - Tightly coupled to Next.js ecosystem (we use Express)
+- Effort: 2-3 weeks
+
+### Chosen Approach
+**Selected: Option 1 (Passport.js)**
+
+We'll use Passport.js with `passport-google-oauth20` and `passport-github2` strategies because:
+1. Battle-tested security implementation reduces risk
+2. Development time is critical for our Q1 deadline
+3. The additional bundle size (~200KB) is acceptable for our use case
+4. Future authentication methods (SAML, LDAP) will be easier to add
+
+**Architecture:**
+- Express.js middleware chain: Request → Passport.authenticate() → Route handler
+- User data flow: OAuth Provider → Passport Strategy → User Service → Database
+- Session management: Express-session with Redis store
+- Token storage: Encrypted tokens in PostgreSQL, session IDs in Redis
+
+**Key Components:**
+1. `AuthController`: Handles OAuth callback routes and session management
+2. `UserService`: Creates/updates user accounts from OAuth profile data
+3. `SessionStore`: Redis-backed session storage with 30-day TTL
+4. `AuthMiddleware`: Protects routes requiring authentication
+
+## Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| OAuth provider API changes break auth flow | High | Low | Pin to specific API versions, monitor provider changelogs, add integration tests |
+| Session hijacking via XSS/CSRF | High | Medium | Implement CSRF tokens, use HTTP-only secure cookies, add Content Security Policy headers |
+| User profile data becomes stale | Medium | High | Implement periodic profile refresh (every 7 days), allow manual refresh |
+| Redis outage breaks all sessions | High | Low | Implement Redis clustering for HA, add fallback to database sessions |
+| OAuth client secrets leak | Critical | Low | Use environment variables, never commit to git, rotate secrets quarterly |
+| Passport.js vulnerabilities | Medium | Low | Enable Dependabot alerts, update regularly, have fallback plan to option 2 |
+
+## Acceptance Criteria
+### Requirement: Users can authenticate with Google and GitHub OAuth2
+The system SHALL allow users to sign up and log in using Google and GitHub OAuth2 authorization code flows.
+
+#### Scenario: New user signs up via Google
+- **WHEN** a user completes Google OAuth2 and no local account exists for that identity
+- **THEN** a new account is created and the user is signed in
+
+#### Scenario: New user signs up via GitHub
+- **WHEN** a user completes GitHub OAuth2 and no local account exists for that identity
+- **THEN** a new account is created and the user is signed in
+
+#### Scenario: Existing user logs in via Google
+- **WHEN** a user completes Google OAuth2 and a matching account exists
+- **THEN** the user is signed in without creating a duplicate account
+
+#### Scenario: Existing user logs in via GitHub
+- **WHEN** a user completes GitHub OAuth2 and a matching account exists
+- **THEN** the user is signed in without creating a duplicate account
+
+### Requirement: OAuth profile data is stored on authentication
+The system SHALL persist required user profile attributes from OAuth providers for authenticated users.
+
+#### Scenario: Profile fields are captured from provider response
+- **WHEN** authentication succeeds
+- **THEN** the user's name, email, and avatar are stored/updated from provider data
+
+### Requirement: Session lifecycle is secure and user-controllable
+The system MUST maintain secure sessions, support logout, and enforce configured session expiration behavior.
+
+#### Scenario: Session persists across browser restarts
+- **WHEN** a user closes and reopens the browser within valid session lifetime
+- **THEN** the user remains authenticated
+
+#### Scenario: User logs out successfully
+- **WHEN** an authenticated user invokes logout
+- **THEN** the session is terminated and authentication cookies are cleared
+
+#### Scenario: Inactive session expires
+- **WHEN** no activity occurs for 30 days
+- **THEN** the session is no longer valid and re-authentication is required
+
+### Requirement: Authentication failures and unauthorized access are handled clearly
+The system SHALL provide explicit user feedback for authentication failures and protect restricted routes.
+
+#### Scenario: Failed authentication shows user-friendly message
+- **WHEN** OAuth authentication fails
+- **THEN** the user is shown a clear, actionable error message
+
+#### Scenario: Unauthorized user hits protected route
+- **WHEN** an unauthenticated request targets a protected endpoint
+- **THEN** the request is redirected to login
+
+### Requirement: Security and operational controls are enforced
+The system MUST log authentication events, enable CSRF protection on auth endpoints, and satisfy key performance targets.
+
+#### Scenario: Authentication events are auditable
+- **WHEN** authentication succeeds or fails
+- **THEN** an event is logged with timestamp, user identifier (when available), and provider
+
+#### Scenario: CSRF protection is active
+- **WHEN** authentication endpoints are invoked
+- **THEN** CSRF safeguards are enforced according to framework policy
+
+#### Scenario: OAuth flow performance target is met
+- **WHEN** OAuth authentication is measured in production-like conditions
+- **THEN** 95th percentile completion time is less than 3 seconds
+
+### Requirement: Test coverage validates critical auth flows
+The implementation MUST include integration tests for happy-path and error-path behavior across both OAuth providers.
+
+#### Scenario: Integration tests cover provider success and failure paths
+- **WHEN** the authentication test suite is executed
+- **THEN** both Google and GitHub flows are validated for successful and failure outcomes
+
+## Implementation Tasks
+- [ ] Set up OAuth2 applications in Google Cloud Console and GitHub Developer Settings
+- [ ] Configure OAuth callback URLs for dev/staging/production environments
+- [ ] Install and configure Passport.js with Google and GitHub strategies
+- [ ] Implement OAuth callback routes (`/auth/google/callback`, `/auth/github/callback`)
+- [ ] Create User model with OAuth provider fields (provider, providerId, email, name, avatarUrl)
+- [ ] Implement UserService with `findOrCreateFromOAuthProfile()` method
+- [ ] Set up Redis session store with express-session
+- [ ] Implement authentication middleware (`isAuthenticated`, `requireAuth`)
+- [ ] Add logout route that destroys session and clears cookies
+- [ ] Create login page UI with "Sign in with Google" and "Sign in with GitHub" buttons
+- [ ] Implement CSRF protection using `csurf` middleware
+- [ ] Add authentication event logging to audit service
+- [ ] Write unit tests for UserService OAuth profile handling
+- [ ] Write integration tests for complete OAuth flow (both providers)
+- [ ] Set up monitoring alerts for authentication failures > 5% threshold
+- [ ] Update API documentation with authentication requirements
+- [ ] Perform security review of OAuth implementation
+- [ ] Load test authentication endpoints to validate NFR4 (1000 concurrent requests)
+
+## Open Questions
+- Q: Should we implement "remember me" functionality for longer session duration?
+  - Decision needed by: Product Manager by 2026-03-05
+- Q: What happens if user's email from OAuth provider changes?
+  - Impact: May create duplicate accounts or lose existing account access
+- Q: Do we support account deletion? If so, what happens to OAuth tokens?
+  - Compliance consideration for GDPR
+- Q: Should we allow multiple OAuth providers per user account in the future?
+  - Would require account linking flow not in current scope
+- Q: What's the UX for users who log in with different providers using same email?
+  - Current approach: treat as separate accounts; future enhancement for linking
+
+## Notes
+- Design mockups for login page: https://figma.com/file/abc123 (internal link)
+- Related GitHub discussion on OAuth security: https://github.com/simplespec/simplespec/discussions/42
+- Competitive analysis: Analyzed auth flows of 5 competitors (see attached document)
+- OAuth2 RFC 6749: https://datatracker.ietf.org/doc/html/rfc6749
+- Security best practices: https://oauth.net/2/oauth-best-practice/
+- Consider migration path from old password-based accounts (separate spec needed)

package/.simplespec/templates/spec-template.md

@@ -0,0 +1,128 @@
+---
+name: <spec name>
+description: <short description of the spec - one sentence summary>
+metadata:
+  created_date: <yyyy-mm-dd>
+  last_updated: <yyyy-mm-dd>
+  author: <author name or role>
+  status: <draft | in-review | approved | implemented | deprecated>
+---
+
+# <spec name>
+
+## Summary
+<!-- 2-3 sentence overview: What are we building and why? Should answer: What problem does this solve? -->
+
+## Goals
+<!-- Specific, measurable objectives this spec aims to achieve. Use bullet points. -->
+<!-- Example: Enable users to authenticate via OAuth2 providers (Google, GitHub) -->
+
+## Non-goals
+<!-- Explicitly state what this spec will NOT address to prevent scope creep -->
+<!-- Example: Single Sign-On (SSO) integration - this will be addressed in a separate spec -->
+
+## Requirements
+
+### Functional Requirements
+<!-- What the system must do. Be specific and testable. -->
+<!-- Example: 
+- FR1: System must support login via Google OAuth2
+- FR2: System must store user profile data (email, name, avatar) from OAuth provider
+-->
+
+### Non-functional Requirements
+<!-- Performance, security, scalability, compliance requirements -->
+<!-- Example:
+- NFR1: Authentication flow must complete within 3 seconds
+- NFR2: User credentials must be encrypted at rest using AES-256
+- NFR3: System must support 1000 concurrent authentication requests
+-->
+
+## Dependencies
+<!-- External systems, APIs, libraries, or other specs this depends on -->
+<!-- Example:
+- OAuth2 provider APIs (Google, GitHub)
+- User database schema (see spec: spec:12-user-profile-schema.md)
+- Redis for session storage
+-->
+
+## Proposed Approach
+
+### Options
+<!-- List alternative approaches considered. For each option, include:
+- Brief description
+- Pros
+- Cons
+- Estimated effort
+-->
+
+<!-- Example:
+**Option 1: Use Passport.js**
+- Pros: Well-established, many OAuth strategies available
+- Cons: Heavyweight, may include features we don't need
+- Effort: 2 weeks
+
+**Option 2: Implement OAuth2 flow manually**
+- Pros: Full control, minimal dependencies
+- Cons: More code to maintain, security risks if done incorrectly
+- Effort: 3-4 weeks
+-->
+
+### Chosen Approach
+<!-- Describe the selected approach and justify why it was chosen over alternatives -->
+<!-- Include high-level architecture, key components, and how they interact -->
+
+## Risks & Mitigations
+<!-- Identify potential problems and how to address them -->
+<!-- Example:
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| OAuth provider API changes | High | Low | Version lock APIs, monitor provider changelogs |
+| Session hijacking | High | Medium | Implement CSRF tokens, secure cookie flags |
+-->
+
+## Acceptance Criteria
+<!-- Write acceptance criteria in requirement/scenario format (OpenSpec style), not checkboxes. -->
+<!-- Use this structure:
+### Requirement: <capability statement>
+The system SHALL/MUST <clear, testable requirement sentence>.
+
+#### Scenario: <specific behavior>
+- **WHEN** <condition/event>
+- **THEN** <expected outcome>
+--->
+<!-- Guidance:
+- Each Requirement should represent one capability area.
+- Add multiple Scenarios per Requirement to cover happy path, error path, and boundary behavior.
+- Scenarios must be measurable and directly testable.
+- Prefer explicit terms such as SHALL/MUST and avoid vague wording.
+-->
+
+## Implementation Tasks
+<!-- Break down into concrete, independently deliverable tasks. Use checkboxes and keep tasks 1-3 days in size. Order by dependencies. -->
+<!-- Example:
+- [ ] Set up OAuth2 client credentials in Google/GitHub developer consoles
+- [ ] Implement OAuth2 callback endpoint
+- [ ] Create user session management service
+- [ ] Add authentication middleware to protected routes
+- [ ] Implement logout functionality
+- [ ] Add authentication UI components (login button, user menu)
+- [ ] Write integration tests for OAuth flow
+- [ ] Update API documentation
+-->
+
+## Open Questions
+<!-- Unresolved questions that need stakeholder input or further research -->
+<!-- Example:
+- Q: Should we support multi-factor authentication (MFA) in this phase?
+- Q: What should happen to user data if they revoke OAuth access?
+- Q: Do we need to support account linking (same user, multiple OAuth providers)?
+-->
+
+## Notes
+<!-- Any additional context, links to related discussions, design mockups, etc. -->
+<!-- Example:
+- Design mockups: https://figma.com/...
+- Related discussion: https://github.com/org/repo/issues/123
+- Competitive analysis: see attached document
+-->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristoffer Svanmark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+<p align="center">
+  <img src="assets/simplespec-logo-light.png" alt="SimpleSpec logo" width="220" />
+</p>
+
+<p align="center">
+  <strong>Spec-driven development for teams building with AI.</strong><br />
+  Turn rough ideas into clear specs your coding agent can actually execute.
+</p>
+
+---
+
+## Why SimpleSpec?
+
+Most AI coding workflows break down in the same place: **unclear intent**.
+
+SimpleSpec gives you a lightweight, repeatable structure for defining what to build before generation starts. It helps your agent ship work that is:
+
+- ✅ Aligned with your actual requirements
+- ✅ Consistent across features and contributors
+- ✅ Easier to review, test, and iterate
+
+---
+
+## What it does
+
+SimpleSpec helps you:
+
+- Create structured feature specifications
+- Apply specs in a consistent implementation workflow
+- Reduce ambiguity between product ideas and generated code
+- Improve output quality from your AI runtime of choice
+
+---
+
+## Quick start
+
+```bash
+npx simplespec@latest
+```
+
+That’s it. Follow the guided flow and start building with clearer direction.
+
+### Create a spec
+
+Use this command as your core workflow:
+
+**Create a new spec from an idea**
+```text
+/spec-new Build a task dashboard with filters, sorting, and bulk actions
+```
+This generates a structured spec under `.simplespec/specs/` with clear requirements, acceptance criteria, and implementation tasks.
+
+   > `/spec-new` will ask if you want to continue directly into implementation.
+
+---
+
+## Built for the AI era
+
+SimpleSpec is designed for modern, agent-assisted development:
+
+- Human-readable specs
+- Repeatable execution patterns
+- Better prompts through better structure
+
+When your specs are clear, your code gets better.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/assets/simplespec-logo.txt

@@ -0,0 +1,6 @@
+   _____ _                 __    _____
+  / ___/(_)___ ___  ____  / /__ / ___/____  ___  _____
+  \__ \/ / __ `__ \/ __ \/ / _ \\__ \/ __ \/ _ \/ ___/
+ ___/ / / / / / / / /_/ / /  __/__/ / /_/ /  __/ /__
+/____/_/_/ /_/ /_/ .___/_/\___/____/ .___/\___/\___/
+                /_/               /_/

package/dist/bin/install.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { loadRuntimes } from "./runtimes/index.js";
+import prompts from 'prompts';
+import chalk from 'chalk';
+import Runtime from "./runtimes/Runtime.js";
+import { readFile } from 'node:fs/promises';
+await loadRuntimes();
+const context = {
+    runtimes: []
+};
+async function printAsciiLogo() {
+    const logoPathCandidates = [
+        new URL('../assets/simplespec-logo.txt', import.meta.url),
+        new URL('../../assets/simplespec-logo.txt', import.meta.url),
+        `${process.cwd()}/assets/simplespec-logo.txt`
+    ];
+    for (const pathCandidate of logoPathCandidates) {
+        try {
+            const logo = await readFile(pathCandidate, 'utf8');
+            console.log(logo);
+            return;
+        }
+        catch {
+            // Try the next candidate path.
+        }
+    }
+    throw new Error('Unable to load ASCII logo from assets/simplespec-logo.txt');
+}
+async function printIntro() {
+    const packageJsonPathCandidates = [
+        new URL('../package.json', import.meta.url),
+        new URL('../../package.json', import.meta.url),
+        `${process.cwd()}/package.json`
+    ];
+    let version = 'unknown';
+    for (const pathCandidate of packageJsonPathCandidates) {
+        try {
+            const packageJsonRaw = await readFile(pathCandidate, 'utf8');
+            ({ version } = JSON.parse(packageJsonRaw));
+            break;
+        }
+        catch {
+            // Try the next candidate path.
+        }
+    }
+    console.log(`SimpleSpec ${chalk.gray(`v${version}`)}`);
+    console.log(`A simple and lightwiehgt specification framework for AI agents.`);
+    console.log(`Installs ${chalk.inverse('./.agents')} directory by default - symlinks to agent specific directories as selected.`);
+    console.log('');
+}
+async function askRuntime() {
+    const response = await prompts({
+        type: 'multiselect',
+        name: 'runtimes',
+        instructions: 'Use space to select, enter to confirm',
+        message: 'Select runtimes to support',
+        choices: Runtime.listAvailableRuntimes().map(({ runtime, name }) => ({
+            title: name,
+            value: runtime
+        })),
+    });
+    context.runtimes = response.runtimes;
+    return response;
+}
+async function installRuntimes() {
+    for (const runtime of context.runtimes) {
+        const runtimeInstance = Runtime.getRuntime(runtime);
+        await runtimeInstance.install();
+    }
+}
+async function run() {
+    await printAsciiLogo();
+    await printIntro();
+    await askRuntime();
+    await installRuntimes();
+}
+run();

package/dist/bin/runtimes/Codex.js

@@ -0,0 +1,15 @@
+import Runtime from "./Runtime.js";
+class Codex extends Runtime {
+    async install() {
+        await super.install();
+        console.log('Installing Codex runtime...');
+        await this.symlinkAgentDirectoriesToRuntime('.codex', [{ source: 'skills' }]);
+        // Codex runtime-specific install behavior goes here.
+    }
+    uninstall() {
+        super.uninstall();
+        // Codex runtime-specific uninstall behavior goes here.
+    }
+}
+Runtime.registerRuntime('codex', 'Codex', '.codex', Codex);
+export default Codex;

package/dist/bin/runtimes/Kilocode.js

@@ -0,0 +1,15 @@
+import Runtime from "./Runtime.js";
+class Kilocode extends Runtime {
+    async install() {
+        await super.install();
+        console.log('Installing Kilo Code runtime...');
+        await this.symlinkAgentDirectoriesToRuntime('.kilocode', [{ source: 'skills' }]);
+        // Kilocode runtime-specific install behavior goes here.
+    }
+    uninstall() {
+        super.uninstall();
+        // Kilocode runtime-specific uninstall behavior goes here.
+    }
+}
+Runtime.registerRuntime('kilocode', 'Kilo Code', '.kilocode', Kilocode);
+export default Kilocode;

package/dist/bin/runtimes/Runtime.js

@@ -0,0 +1,135 @@
+import { access, cp, mkdir } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { symlinkDirectoriesFromAgentsToRuntime, } from "./symlinkDirectories.js";
+const runtimes = {};
+const registeredRuntimes = {};
+const FRAMEWORK_BASE_DIRECTORY_MAPPINGS = [
+    {
+        source: 'skills',
+        target: '.agents/skills',
+    },
+    {
+        source: '.simplespec',
+        target: '.simplespec',
+    },
+];
+function getInstallationDirectory() {
+    const currentWorkingDirectory = process.cwd();
+    const initialWorkingDirectory = process.env.INIT_CWD?.trim();
+    const npmPackageJsonPath = process.env.npm_package_json;
+    if (!initialWorkingDirectory || !npmPackageJsonPath) {
+        return currentWorkingDirectory;
+    }
+    const npmScriptDirectory = dirname(npmPackageJsonPath);
+    if (resolve(currentWorkingDirectory) === resolve(npmScriptDirectory)) {
+        return initialWorkingDirectory;
+    }
+    return currentWorkingDirectory;
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveFrameworkBaseSourceDirectory(sourceDirectory) {
+    const installationDirectory = getInstallationDirectory();
+    const runtimeFileDirectory = dirname(fileURLToPath(import.meta.url));
+    const sourceDirectoryCandidates = [
+        join(runtimeFileDirectory, '..', '..', sourceDirectory),
+        join(runtimeFileDirectory, '..', '..', '..', sourceDirectory),
+        join(installationDirectory, sourceDirectory),
+    ];
+    for (const sourceDirectoryCandidate of sourceDirectoryCandidates) {
+        if (await pathExists(sourceDirectoryCandidate)) {
+            return sourceDirectoryCandidate;
+        }
+    }
+    throw new Error(`Unable to resolve framework base source directory: ${sourceDirectory}`);
+}
+async function installFrameworkBaseDirectories() {
+    const installationDirectory = getInstallationDirectory();
+    for (const { source, target } of FRAMEWORK_BASE_DIRECTORY_MAPPINGS) {
+        const sourceDirectory = await resolveFrameworkBaseSourceDirectory(source);
+        const targetDirectory = join(installationDirectory, target);
+        if (resolve(sourceDirectory) === resolve(targetDirectory)) {
+            continue;
+        }
+        await mkdir(dirname(targetDirectory), { recursive: true });
+        if (source === '.simplespec') {
+            await cp(sourceDirectory, targetDirectory, {
+                recursive: true,
+                force: true,
+                filter: (sourcePath) => {
+                    const sourceRelativePath = relative(sourceDirectory, sourcePath);
+                    if (!sourceRelativePath) {
+                        return true;
+                    }
+                    return sourceRelativePath !== 'specs' && !sourceRelativePath.startsWith(`specs${sep}`);
+                },
+            });
+            continue;
+        }
+        await cp(sourceDirectory, targetDirectory, {
+            recursive: true,
+            force: true,
+        });
+    }
+}
+class Runtime {
+    runtime;
+    static globalInstallCompleted = false;
+    constructor(runtime) {
+        if (new.target === Runtime) {
+            throw new Error('Use Runtime.getRuntime() instead of new.');
+        }
+        this.runtime = runtime;
+    }
+    async install() {
+        if (Runtime.globalInstallCompleted) {
+            return;
+        }
+        console.log('Installing global runtime...');
+        await installFrameworkBaseDirectories();
+        Runtime.globalInstallCompleted = true;
+    }
+    uninstall() {
+        // Shared uninstall behavior for all runtimes goes here.
+    }
+    async symlinkAgentSkillsToRuntime(runtimeDirectory) {
+        await this.symlinkAgentDirectoriesToRuntime(runtimeDirectory, [{ source: 'skills' }]);
+    }
+    async symlinkAgentDirectoriesToRuntime(runtimeDirectory, mappings) {
+        await symlinkDirectoriesFromAgentsToRuntime(runtimeDirectory, mappings);
+    }
+    static registerRuntime(runtime, name, runtimePath, RuntimeClass) {
+        registeredRuntimes[runtime] = {
+            name,
+            runtimePath,
+            RuntimeClass,
+        };
+    }
+    static listAvailableRuntimes() {
+        return Object.entries(registeredRuntimes).map(([runtime, { name, runtimePath }]) => ({
+            runtime,
+            name,
+            runtimePath,
+        }));
+    }
+    static getRuntime(runtime) {
+        if (!runtimes[runtime]) {
+            const registeredRuntime = registeredRuntimes[runtime];
+            if (!registeredRuntime) {
+                throw new Error(`Runtime "${runtime}" is not registered.`);
+            }
+            runtimes[runtime] = new registeredRuntime.RuntimeClass(runtime);
+        }
+        return runtimes[runtime];
+    }
+}
+export { runtimes };
+export default Runtime;

package/dist/bin/runtimes/index.js

@@ -0,0 +1,33 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readdir } from 'node:fs/promises';
+import { dirname, extname, basename } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const RUNTIME_FILE_EXTENSIONS = new Set(['.js', '.ts']);
+const EXCLUDED_RUNTIME_FILES = new Set(['Runtime', 'index']);
+async function loadRuntimes() {
+    const currentFilePath = fileURLToPath(import.meta.url);
+    const currentDir = dirname(currentFilePath);
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile()) {
+            continue;
+        }
+        const extension = extname(entry.name);
+        const fileNameWithoutExtension = basename(entry.name, extension);
+        if (!RUNTIME_FILE_EXTENSIONS.has(extension)) {
+            continue;
+        }
+        if (EXCLUDED_RUNTIME_FILES.has(fileNameWithoutExtension)) {
+            continue;
+        }
+        await import(__rewriteRelativeImportExtension(pathToFileURL(`${currentDir}/${entry.name}`).href));
+    }
+}
+export { loadRuntimes };

package/dist/bin/runtimes/symlinkDirectories.js

@@ -0,0 +1,44 @@
+import { lstat, mkdir, readdir, rm, symlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+function getInstallationDirectory() {
+    const currentWorkingDirectory = process.cwd();
+    const initialWorkingDirectory = process.env.INIT_CWD?.trim();
+    const npmPackageJsonPath = process.env.npm_package_json;
+    if (!initialWorkingDirectory || !npmPackageJsonPath) {
+        return currentWorkingDirectory;
+    }
+    const npmScriptDirectory = dirname(npmPackageJsonPath);
+    if (resolve(currentWorkingDirectory) === resolve(npmScriptDirectory)) {
+        return initialWorkingDirectory;
+    }
+    return currentWorkingDirectory;
+}
+async function symlinkDirectoriesFromAgentsToRuntime(runtimeDirectory, mappings) {
+    for (const mapping of mappings) {
+        const installationDirectory = getInstallationDirectory();
+        const sourceDirectoryName = mapping.source;
+        const targetDirectoryName = mapping.target ?? mapping.source;
+        const sourceDirectory = join(installationDirectory, '.agents', sourceDirectoryName);
+        const targetDirectory = join(installationDirectory, runtimeDirectory, targetDirectoryName);
+        await mkdir(targetDirectory, { recursive: true });
+        const entries = await readdir(sourceDirectory, { withFileTypes: true });
+        for (const entry of entries) {
+            const sourceEntryPath = join(sourceDirectory, entry.name);
+            const targetEntryPath = join(targetDirectory, entry.name);
+            try {
+                await lstat(targetEntryPath);
+                await rm(targetEntryPath, { recursive: true, force: true });
+            }
+            catch {
+                // Target does not exist yet.
+            }
+            const relativeSourceEntryPath = relative(targetDirectory, sourceEntryPath);
+            if (isAbsolute(relativeSourceEntryPath)) {
+                throw new Error(`Expected relative symlink target, but got: ${relativeSourceEntryPath}`);
+            }
+            const symlinkType = entry.isDirectory() ? 'dir' : 'file';
+            await symlink(relativeSourceEntryPath, targetEntryPath, symlinkType);
+        }
+    }
+}
+export { symlinkDirectoriesFromAgentsToRuntime };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "simplespec",
+  "version": "0.1.0",
+  "description": "A simple spec-driven framework",
+  "type": "module",
+  "main": "dist/bin/install.js",
+  "bin": {
+    "simplespec": "dist/bin/install.js"
+  },
+  "files": [
+    "dist/bin/**",
+    "skills/**",
+    ".simplespec/**",
+    "assets/simplespec-logo.txt",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "dev": "tsx bin/install.ts",
+    "install:run": "npm run build && node dist/bin/install.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "node --import tsx --test \"tests/**/*.test.ts\"",
+    "prepack": "npm run clean && npm run build",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.3",
+    "@types/node": "^22.13.10",
+    "@types/prompts": "^2.4.9",
+    "eslint": "^9.39.3",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.56.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Svanmark/simplespec.git"
+  },
+  "author": "Kristoffer Svanmark",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Svanmark/simplespec/issues"
+  },
+  "homepage": "https://github.com/Svanmark/simplespec#readme",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "prompts": "^2.4.2"
+  }
+}

package/skills/spec-apply/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: spec-apply
+description: Implement an existing product/engineering specification using the spec-driven development workflow. Use when asked to apply a spec and deliver implementation-ready code changes.
+metadata:
+  version: "0.1"
+---
+
+# /spec-apply - Implement spec
+
+## Inputs
+
+Input can be either of:
+
+- A spec id (spec:<number>).
+  - Browse `.simplespec/specs/` to find the spec file.
+- File path to a spec file.
+- Empty.
+  - Detect spec reference from context (e.g., from a previous message or conversation).
+
+## Outputs
+
+- Implemented code changes that satisfy the selected spec.
+- Tests added/updated when the repository has tests or when explicitly requested in the spec/task.
+- Validation artifacts from local checks (for example lint/typecheck/tests/build where applicable).
+- A concise implementation summary including what was completed, what was verified, and any unresolved blockers.
+
+## Process
+
+1. **Resolve the target spec**
+   - If input is a spec id, locate matching file under `.simplespec/specs/`.
+   - If input is empty, infer the most recent/active spec reference from context.
+   - If no clear target can be resolved, ask a focused follow-up question.
+
+2. **Read and extract implementation scope**
+   - Parse: Summary, Goals, Non-goals, Requirements, Acceptance Criteria, and Implementation Tasks.
+   - Convert requirements into an execution checklist.
+   - Treat ambiguous or conflicting requirements as blockers and ask targeted clarification only when necessary.
+
+3. **Align with repository conventions before coding**
+   - Detect language, framework, architecture, and naming/style patterns from existing files.
+   - Reuse existing abstractions and patterns before introducing new ones.
+   - Prefer minimal, focused diffs that preserve established project structure.
+
+4. **Implement iteratively**
+   - Complete work in dependency order.
+   - Keep commits/changes scoped to spec requirements and explicit acceptance criteria.
+   - Avoid out-of-scope enhancements unless they are required to make the spec implementation correct.
+
+5. **Parallelize with orchestration when beneficial**
+   - The skill may orchestrate/spawn multiple agents to implement independent workstreams in parallel.
+   - Split by clear boundaries (for example backend, frontend, tests, docs) to minimize merge conflicts.
+   - Define contracts up front (shared types/interfaces, acceptance criteria ownership, file boundaries).
+   - Reconcile outputs into a single consistent implementation before validation.
+
+6. **Apply testing strategy**
+   - If tests exist in the repository, add/update tests to cover all new behavior and relevant edge cases.
+   - If the spec or user instruction requires tests, treat tests as mandatory deliverables.
+   - Map tests directly to acceptance criteria so each requirement is explicitly verified.
+   - Prefer small, focused tests with a single assertion intent (for example filtering, boundary behavior, sorting, validation) over one large mixed scenario.
+   - Include both happy path and failure-path coverage (invalid input, missing entities, boundary conditions).
+   - Keep tests deterministic (stable fixtures, explicit ordering assertions where ordering matters, no time/network randomness).
+   - When one broad test exists, split it into requirement-aligned tests to improve failure diagnosis and maintainability.
+   - Run project-appropriate checks (for example test, typecheck, lint, build) and fix issues caused by the implementation.
+
+7. **Frontend verification (when applicable)**
+   - For UI/frontend implementations, use the agent browser to validate rendered UI and key user flows.
+   - Verify that behavior matches acceptance criteria (including visible states and interaction outcomes).
+   - Address UI/functional regressions found during browser validation.
+
+8. **Review and iterate**
+   - Perform a short self-review against:
+     - Spec requirements and acceptance criteria coverage.
+     - Test quality and reliability.
+     - Code quality and robustness (error handling/edge cases).
+   - Iterate on implementation until no known gaps remain or a clear blocker is documented.
+
+9. **Report completion**
+   - Summarize implemented items mapped to acceptance criteria.
+   - List tests/checks executed and outcomes.
+   - Document any follow-up items explicitly marked out-of-scope or blocked.
+
+## Guardrails
+
+- Do not implement features outside spec scope unless required for correctness.
+- Do not skip tests when test infrastructure exists or when testing is explicitly required.
+- Do not claim frontend verification without using the browser for frontend work.
+- Prefer repository-standard patterns over introducing new architecture.
+- Escalate blockers early with precise questions rather than making risky assumptions.
+- When parallelizing with multiple agents, always perform a final integration pass to resolve conflicts and ensure end-to-end correctness.

package/skills/spec-new/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: spec-new
+description: Create a new product/engineering specification using our spec-driven development workflow. Use when asked to draft a new spec, define requirements, acceptance criteria, or produce a spec for a feature.
+metadata:
+  version: "0.1"
+---
+
+# /spec-new - Create a new simple spec
+
+## Inputs
+
+A text describing the idea for the feature to implement. It can be:
+- A short description of the feature.
+- A longer, more detailed description capturing requirements and approaches.
+- Link(s) to relevant documents or resources. Link(s) to external project management tools like Jira or Confluence.
+
+## Outputs
+A spec file created at `.simplespec/specs/spec:<number>-<slug>.md` based on `.simplespec/templates/spec-template.md`. Theres an example spec available under `.simplespec/examples/example-spec.md`
+
+### Slug Generation Rules
+Generate the `<slug>` from the spec name using these rules:
+- Convert to lowercase
+- Replace spaces with hyphens
+- Remove special characters (keep only alphanumeric and hyphens)
+- Remove consecutive hyphens
+- Trim hyphens from start/end
+- Maximum 50 characters
+- Examples:
+  - "User Authentication" → `user-authentication`
+  - "API Rate Limiting (v2)" → `api-rate-limiting-v2`
+  - "Real-time Chat Feature!!!" → `real-time-chat-feature`
+
+## Process
+1. **Parse Input**: Extract key information from the input text or linked resources. If links are inaccessible, notify and ask for alternative sources or proceed with available information.
+
+2. **Analyze Requirements**: Identify the main components, dependencies, and requirements of the feature. Consider:
+   - Core functionality needed
+   - System components affected
+   - Integration points
+   - Potential technical challenges
+
+3. **Gather Missing Details**: Ask targeted questions only for crucial information gaps that significantly impact the spec. Examples of "major/crucial" details:
+   - Target users or use cases that fundamentally change the approach
+   - Performance requirements (scale, latency expectations)
+   - Security or compliance requirements
+   - Integration dependencies or constraints
+   - MVP scope vs. future enhancements
+
+4. **Complete Spec Sections**: Fill in all template sections with extracted and analyzed information. Ensure:
+   - Each section captures all relevant details and is well-structured
+   - Use "N/A" for sections that don't apply (with brief justification)
+   - Leave "Open Questions" for items needing stakeholder input
+   - Be specific and avoid vague language
+
+5. **Break Down Tasks**: Create implementation tasks that are:
+   - Independently testable and deployable
+   - Sized appropriately (1-3 days of work ideally)
+   - Ordered by logical dependencies
+   - Formatted as markdown checkboxes
+   - Include brief acceptance criteria per task
+
+6. **Validate Completeness**: Review the spec against success criteria (see below). Iterate if:
+   - Any required section is missing or too vague
+   - Acceptance criteria are not measurable
+   - Tasks are not granular enough or have unclear scope
+   - Requirements contain ambiguities
+
+7. **Handle Duplicates**: Before saving, check if a spec with similar name/slug exists in `.simplespec/specs/`. If found, either:
+   - Append a numeric suffix to the slug (e.g., `-2`, `-3`)
+   - Ask if this should update an existing spec
+
+8. **Save Spec File**: Create the spec file with proper frontmatter metadata and naming:
+   - Set `created_date` to current date in YYYY-MM-DD format
+   - Set `last_updated` to creation date
+   - Generate slug per rules above
+   - Determine `<number>` by listing files in `.simplespec/specs/`, extracting existing `spec:<number>-*.md` prefixes, and using the next incremental number (start at `1` when none exist)
+
+9. **Ask if user want to proceed to implementing the spec.**
+    - Ask the user if they want to proceed with implementing the spec, providing options to:
+    - Start implementation immediately, refer to the `spec-apply` skill.
+
+## Error Handling
+
+- **Inaccessible Links**: If external links can't be accessed, inform the user and  ask if you shall proceed with available information or request alternatives
+- **Incomplete Input**: If critical information is missing and can't be inferred, ask specific questions rather than making assumptions
+- **Duplicate Detection**: Check for existing specs with same/similar slugs before saving
+- **Invalid Spec Name**: If the name can't generate a valid slug, ask for clarification
+
+## Success Criteria
+
+A high-quality spec should meet these criteria:
+- ✅ All required template sections are completed (or marked N/A with justification)
+- ✅ Summary clearly explains what and why in 2-3 sentences
+- ✅ Goals and Non-goals are specific and mutually exclusive
+- ✅ Requirements are unambiguous and verifiable
+- ✅ Acceptance criteria are measurable and testable
+- ✅ Implementation tasks are granular, ordered, and independently deliverable
+- ✅ Risks identify potential issues with mitigation strategies
+- ✅ No ambiguous or vague language (avoid "should", "might", "probably")
+- ✅ Dependencies on other systems/specs are explicitly documented
+- ✅ The spec can be handed off to an engineer without additional clarification