@intoinside/praxis 1.0.1

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,99 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces. Examples
+of representing our community include using an official e-mail address, posting
+via an official social media account, or acting as an appointed representative
+at an online or offline event.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation
+and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including
+unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding
+interactions in community spaces as well as external channels like social media. Violating these terms may lead to a
+temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified
+period of time. No public or private interaction with the people involved, including unsolicited interaction with those
+enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate
+behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq]
+[FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to Praxis
+
+Thank you for your interest in contributing to Praxis! We welcome
+contributions from the community to help improve the intent/spec-driven
+development experience.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Contributing Guidelines](#contributing-guidelines)
+- [Adding New Agent Support](#adding-new-agent-support)
+- [Testing](#testing-requirements)
+- [Documentation](#documentation)
+- [Release Process](#release-process)
+- [Community](#community)
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+
+   ```bash
+   git clone https://github.com/your-username/praxis.git
+   cd praxis
+   ```
+
+3. **Set up the development environment** (see [Development Setup](#development-setup))
+4. **Create a feature branch**:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+5. **Make your changes** and ensure tests pass
+6. **Submit a pull request** with a clear description of your changes
+
+## Development Setup
+
+### Prerequisites
+
+- **Git**
+- **Supported AI agent** (for testing)
+
+## Contributing Guidelines
+
+### Code Standards
+
+- **Follow PEP 8** for Python code style
+- **Use type hints** for all function signatures
+- **Write docstrings** for all public functions and classes
+- **Keep functions small** and focused on single responsibilities
+- **Use meaningful variable names** and avoid abbreviations
+
+### Commit Guidelines
+
+- **Use conventional commits**: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:`
+- **Write clear commit messages** explaining what and why
+- **Reference issues** when applicable: `Fixes #123`, `Closes #456`
+- **Keep commits atomic** - one logical change per commit
+
+### Pull Request Process
+
+1. **Update documentation** if you're changing functionality
+2. **Add tests** for new features or bug fixes
+3. **Submit your PR** with a clear description
+
+### Testing Requirements
+
+- **Unit tests** for all new functionality
+- **Integration tests** for CLI commands and agent interactions
+- **Cross-platform tests** (Windows, macOS, Linux)
+- **Agent compatibility tests** for all supported AI agents
+
+## Documentation
+
+### Documentation Structure
+
+- **`README.md`**: Main project overview and getting started guide
+- **Inline documentation**: Code comments and docstrings
+
+### Writing Documentation
+
+- **Use clear, concise language** appropriate for the audience
+- **Include examples** for complex features
+- **Keep documentation in sync** with code changes
+- **Use relative links** for internal references
+- **Test code examples** to ensure they work
+
+## Community
+
+### Getting Help
+
+- **GitHub Issues**: For bug reports and feature requests
+- **GitHub Discussions**: For questions and discussions
+- **Documentation**: Check the docs first for common questions
+
+### Code of Conduct
+
+Please read and follow our [Code of Conduct](./CODE_OF_CONDUCT.md) when participating in the Praxis community.
+
+### Recognition
+
+Contributors who make significant improvements to Praxis may be recognized in the project documentation or release notes.
+
+---
+
+Thank you for contributing! Your help makes Praxis better for everyone.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raffaele Intorcia
+
+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/MAINTAINERS.md

@@ -0,0 +1,9 @@
+# Maintainers
+
+People who maintain and guide Praxis.
+
+## Core Maintainers
+
+| Name | GitHub | Role |
+|------|--------|------|
+| Raffaele Intorcia | [@intoinside](https://github.com/intoinside) | Lead maintainer |

package/README.md

@@ -0,0 +1,319 @@
+# Praxis
+
+```
+ ███████████                                   ███         
+░░███░░░░░███                                 ░░░          
+ ░███    ░███ ████████   ██████   █████ █████ ████   █████ 
+ ░██████████ ░░███░░███ ░░░░░███ ░░███ ░░███ ░░███  ███░░  
+ ░███░░░░░░   ░███ ░░░   ███████  ░░░█████░   ░███ ░░█████ 
+ ░███         ░███      ███░░███   ███░░░███  ░███  ░░░░███
+ █████        █████    ░░████████ █████ █████ █████ ██████ 
+░░░░░        ░░░░░      ░░░░░░░░ ░░░░░ ░░░░░ ░░░░░ ░░░░░░  
+```
+
+**Praxis** is a development framework that bridges **Intent‑Driven Development (IDD)** and **Spec‑Driven Development (SDD)** into a single, coherent workflow.
+
+It relays on [Intended](https://github.com/Nom-nom-hub/Intended) and [OpenSpec](https://github.com/Fission-AI/OpenSpec).
+
+Praxis helps teams start from *why* they are building something, derive *what* must be built in the form of explicit specifications, and continuously verify that the *how* (the code) never diverges from the original intent.
+
+It is designed to be:
+
+* **AI‑native** (usable from AI chats inside modern IDEs)
+* **CLI‑first** (works without any IDE or AI integration)
+* **Intent‑centric** (intent is the primary source of truth)
+
+---
+
+## Core Concepts
+
+### Intent
+
+An **Intent** describes the purpose, value, and constraints of a feature or system.
+It answers the question:
+
+> *Why are we building this?*
+
+Intents are technology‑agnostic and do not describe APIs, UI, or implementation details.
+
+---
+
+### Specification (Spec)
+
+A **Specification** is a formal, verifiable description derived from an Intent.
+It answers the question:
+
+> *What must the system do to satisfy the intent?*
+
+Specs act as contracts and can be translated into:
+
+* behavioral rules
+* acceptance criteria
+* API contracts
+* test cases
+
+---
+
+### Drift Detection
+
+Praxis continuously checks for **semantic drift**:
+
+* specs that no longer satisfy the intent
+* code that implements features not justified by any intent
+
+---
+
+## What Praxis Provides
+
+### 1. Intent Management
+
+* Create, update, and validate intents
+* Enforce intent structure and clarity
+* Track intent evolution over time
+
+### 2. Intent Modeling
+
+* Extract capabilities, events, and states from intents
+* Provide a bridge between intent and specification
+
+### 3. Spec Derivation
+
+* Generate initial specifications from intents
+* Maintain traceability between intents and specs
+* Support manual refinement without losing intent linkage
+
+### 4. Spec Validation
+
+* Lock specs as formal contracts
+* Validate implementations against specs
+* Detect missing or incomplete implementations
+
+### 5. Drift Analysis
+
+* Detect features not backed by intent
+* Detect intents no longer satisfied by current specs
+
+### 6. AI & IDE Integration
+
+* Slash‑command friendly design
+* CLI commands that can be mapped to IDE AI chats
+* Optional exposure as a local command server (e.g. MCP‑style)
+
+## Folder structure
+
+```
+.praxis/
+├── intents/
+│   ├── wip/             # Work-in-progress intents
+│   └── archive/         # Archived intents
+├── specs/               # Specifications (OpenSpec)
+│   ├── wip/             # Work-in-progress specs
+│   └── archive/         # Archived specs
+└── templates/           # Templates for intents and specs
+```
+
+### Intent Commands
+
+|Command|Description|Status/Version|
+|-|-|-|
+|`praxis init`|Initialize a new project to be used with Praxis. Templates are provided in the `templates` directory.|✅|
+|`praxis intent create <intent-description>`|Create a new intent.|✅|
+|`praxis intent update <intent-id>`|Update an existing intent.|❔​|
+|`praxis intent validate`|Validate all intents for completeness and consistency.|❌|
+|`praxis intent list`|List all defined intents.|✅|
+
+---
+
+### Intent Modeling Commands
+
+|Command|Description|Status/Version|
+|-|-|-|
+|`praxis intent model <intent-id>`|Generate or update the intent model (capabilities, events, states).|❔​|
+
+---
+
+### Specification Commands
+
+|Command|Description|Status/Version|
+|-|-|-|
+|`praxis spec derive --from-intent <intent-id>`|Generate initial specifications from an intent.|✅|
+|`praxis spec refine <spec-id>`|Manually refine a specification while preserving intent traceability.|❔​|
+|`praxis spec validate <spec-id>`|Validate specs for internal consistency and completeness.|❌|
+|`praxis spec apply <spec-id>`|Implement a specification in code.|❌|
+|`praxis spec archive <spec-id>`|Archive a specification implemented.|❌|
+|`praxis spec delete <spec-id>`|Delete a specific spec.|✅|
+|`praxis spec delete --from-intent <intent-id>`|Delete all specs generated from an intent.|❌|
+|`praxis spec lock <spec-id>`|Lock a specification as a formal contract.|❔​|
+|`praxis spec list --from-intent <intent-id>`|List all specifications and their associated intents.|❌|
+|`praxis spec check`|Verify implementation compliance against locked specs.|❔​|
+
+---
+
+### Analysis Commands
+
+|Command|Description|Status/Version|
+|-|-|-|
+|`praxis analyze impact --from-intent <intent-id>`|Analyze the impact of changes to an intent on specs and code.|❔​|
+|`praxis analyze drift`|Detect intent/spec/code drift.|❔​|
+
+---
+
+### Integration & Runtime Commands
+
+|Command|Description|Status/Version|
+|-|-|-|
+|`praxis serve`|Expose Praxis commands through a local service for IDE or AI integration.|❔​|
+|`praxis commands`|List all available commands in machine‑readable form.|❔​|
+
+---
+
+## Slash Command Usage (IDE / AI Chat)
+
+When integrated into an IDE or AI‑enabled editor, Praxis commands can be invoked as slash commands:
+
+```
+/praxis-intent-create
+/praxis-spec-derive
+/praxis-intent-check
+```
+
+The underlying behavior is identical to the CLI.
+
+---
+
+## Development Flow Overview
+
+The following diagram illustrates how **Intents** and **Specifications** integrate into a standard development lifecycle.
+
+```
+        ┌────────────┐
+        │   Intent   │
+        │   (WHAT)   │
+        │   (WHY)    │
+        └─────┬──────┘
+              │
+              ▼
+     ┌──────────────────┐
+     │ Intent Modeling  │
+     │ (Capabilities,   │
+     │  Events, States) │
+     └────────┬─────────┘
+              │
+              ▼
+        ┌────────────┐
+        │   Specs    │
+        │   (WHAT)   │
+        └─────┬──────┘
+              │
+   ┌──────────┼──────────┐
+   │          │          │
+   ▼          ▼          ▼
+Tests     Contracts   Scenarios
+
+              │
+              ▼
+        ┌────────────┐
+        │    Code    │
+        │   (HOW)    │
+        └─────┬──────┘
+              │
+              ▼
+     ┌─────────────────┐
+     │ Validation &    │
+     │ Drift Detection │
+     └─────┬───────────┘
+           │
+           └───────────────┐
+                           ▼
+                     Intent Check
+```
+
+### How Praxis Fits into Daily Development
+
+* **Before coding**: intents and specs are defined and validated
+* **During coding**: specs act as executable and contractual guidance
+* **After changes**: drift detection ensures alignment with original intent
+
+This allows Praxis to integrate seamlessly with existing workflows such as:
+
+* Agile / Scrum
+* TDD / BDD
+* CI/CD pipelines
+
+---
+
+## Design Philosophy
+
+* **Intent is sacred**: everything must trace back to a reason.
+* **Specs are contracts**: informal requirements are not enough.
+* **Code must justify itself**: no feature without intent.
+* **AI is an assistant, not the authority**: Praxis remains deterministic and auditable.
+
+---
+
+## Installation
+
+Praxis is written in **TypeScript** and distributed as a **Node.js CLI**.
+
+### Prerequisites
+
+* Node.js **>= 18**
+* npm (or compatible package manager)
+
+You can verify your environment with:
+
+```
+node --version
+npm --version
+```
+
+---
+
+### Install (Global)
+
+To install Praxis globally and make the `praxis` command available system-wide:
+
+```
+npm install -g praxis
+```
+
+After installation, verify it works:
+
+```
+praxis --help
+```
+
+---
+
+### Install (Project-local)
+
+You can also install Praxis as a development dependency inside a project:
+
+```
+npm install --save-dev praxis
+```
+
+Then run it via:
+
+```
+npx praxis --help
+```
+
+---
+
+### Using with IDEs and AI Chats
+
+When installed locally or globally, Praxis commands can be mapped to:
+
+* IDE extensions (e.g. VS Code)
+* AI chat slash commands
+* local tool servers (e.g. via `praxis serve`)
+
+The installation method does not change Praxis behavior; it only affects how commands are invoked.
+
+---
+
+## Status
+
+Praxis is under active development.
+APIs, command names, and file formats may evolve.

package/last_error.txt

@@ -0,0 +1,42 @@
+node : (node:14940) ExperimentalWarning: 
+`--experimental-loader` may be removed 
+in the future; instead use `register()`:
+In riga:1 car:1
++ node --loader ts-node/esm src/index.ts 
+--help 2>&1 | Out-File -FilePa ...
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~
+    + CategoryInfo          : NotSpecifi 
+   ed: ((node:14940) Ex...e `register()  
+  `::String) [], RemoteException
+    + FullyQualifiedErrorId : NativeComm 
+   andError
+ 
+--import 'data:text/javascript,import { 
+register } from "node:module"; import { 
+pathToFileURL } from "node:url"; 
+register("ts-node/esm", 
+pathToFileURL("./"));'
+(Use `node --trace-warnings ...` to show 
+where the warning was created)
+(node:14940) [DEP0180] 
+DeprecationWarning: fs.Stats constructor 
+is deprecated.
+(Use `node --trace-deprecation ...` to 
+show where the warning was created)
+Usage: praxis [options] [command]
+
+Praxis: Intent-First Development Framework
+
+Options:
+  -V, --version    output the version number
+  -h, --help       display help for command
+
+Commands:
+  init             Initialize a new project to be used with Praxis
+  intent           Manage intents (the WHY)
+  model [options]  Generate or update the intent model
+  spec             Manage specifications (the WHAT)
+  analyze          Analyze impact and drift
+  integration      IDE and AI integration
+  help [command]   display help for command

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@intoinside/praxis",
+  "version": "1.0.1",
+  "description": "**Praxis** is an intent-first development framework that bridges **Intent‑Driven Development (IDD)** and **Spec‑Driven Development (SDD)** into a single, coherent workflow.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "bin": {
+    "praxis": "src/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intoinside/Praxis.git"
+  },
+  "keywords": [
+    "idd",
+    "sdd",
+    "intent",
+    "spec",
+    "intent-driven",
+    "spec-driven"
+  ],
+  "author": "Raffaele Intorcia",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/intoinside/Praxis/issues"
+  },
+  "homepage": "https://github.com/intoinside/Praxis#readme",
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "commander": "^14.0.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(): Promise<void>;

package/src/commands/init.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import path from 'path';
+export async function initCommand() {
+    const rootDir = process.cwd();
+    const praxisDir = path.join(rootDir, '.praxis');
+    const templatesDir = path.join(praxisDir, 'templates');
+    const intentsDir = path.join(praxisDir, 'intents');
+    const intentsWipDir = path.join(praxisDir, 'intents', 'wip');
+    const intentsArchiveDir = path.join(praxisDir, 'intents', 'archive');
+    const specsDir = path.join(praxisDir, 'specs');
+    const dirs = [praxisDir, templatesDir, intentsDir, intentsWipDir, intentsArchiveDir, specsDir];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+            console.log(`Created directory: ${path.relative(rootDir, dir)}`);
+            // Create a .gitkeep file to ensure the directory is tracked by git
+            fs.writeFileSync(path.join(dir, '.gitkeep'), '');
+        }
+        else {
+            console.log(`Directory already exists: ${path.relative(rootDir, dir)}`);
+        }
+    }
+    // Copy templates from root templates/ to .praxis/templates/
+    const sourceTemplatesDir = path.join(rootDir, 'templates');
+    if (fs.existsSync(sourceTemplatesDir)) {
+        console.log('\nCopying templates...');
+        const templateFiles = fs.readdirSync(sourceTemplatesDir);
+        for (const file of templateFiles) {
+            const sourcePath = path.join(sourceTemplatesDir, file);
+            const targetPath = path.join(templatesDir, file);
+            if (fs.statSync(sourcePath).isFile()) {
+                fs.copyFileSync(sourcePath, targetPath);
+                console.log(`- Copied: ${file}`);
+            }
+        }
+    }
+    else {
+        console.log('\nNo source templates directory found at root. Skipping template copy.');
+    }
+    console.log('\nPraxis project structure initialized successfully!');
+    console.log('You can now start defining intents in .praxis/intents/wip/');
+}