# gjalla CLI
A CLI for organizing, aggregating, and standardizing requirements and architecture information from markdowns written by agentic coding tools.
## Installation
```bash
# Install from PyPI
pip install gjalla
# Install from source
pip install git+https://github.com/elliemdaw/gjalla-cli.git
```
## 🚀 Quick Start
### Organize Documentation
```bash
# Preview what would be organized
gjalla organize <path to project> --dry-run
# Apply the organization
gjalla organize <path to project>
# Undo if needed
# NOTE: undo has only been tested for the most recent action
gjalla undo <path to project>
```
### Aggregate Requirements
```bash
# Parse structured .kiro requirements
gjalla requirements <path to project> --kiro
# List existing requirements
gjalla requirements <path to project> --list
```
## How It Works
### Organization Process
1. **📋 Document Discovery**: Finds all markdown files. Exclude patterns can be defined in .gjallaignore, otherwise falls back to common ignore patterns
2. **🏷️ File Classification**: Uses regex patterns and lightweight NLP (`spacy`) to classify markdown files by type
3. **🔧 Directory Creation**: Creates missing directories as needed (`specs/`, `specs/features/`, `specs/fixes/`, `specs/references/`... see below!)
4. **📦 File Movement**: Moves files to appropriate locations with conflict resolution
5. **💾 Backup**: Saves backup info for undo functionality
### Directory Structure After Organization
```
my-project/
├── aimarkdowns/
│ ├── features/ # User stories, feature specs
│ ├── fixes/ # Bug reports, fixes
│ ├── reference/ # Documentation, guides
│ ├── requirements_001.md # Generated requirements summary
| ├── CLAUDE.md # if found and not excluded, it will be put here
| └── GEMINI.md # if found and not excluded, it will be put here
├── .gjalla/
│ ├── backups/ # Backup files for undo
├── .gjallaignore # for defining exclusion patterns
```
## Requirements
### Kiro
gjalla supports the structure of docs written by Kiro, found in `.kiro` directories:
```
.kiro/
├── specs/
│ ├── feature-name/
│ │ ├── requirements_001.md # Kiro requirements
│ │ ├── design.md # Kiro design
│ │ └── tasks.md # Kiro tasks
│ └── another-feature/
│ └── requirements_001.md
```
### Non-Kiro
_Working on this!_
## 🚧 Coming Next
- [x] **Update Requirements Status**: Mark requirements as implemented/partial/not-implemented
- [ ] **Aggregate Architecture Spec (Kiro Mode)**: Generate comprehensive architecture documentation from .kiro structure
- [ ] **Aggregate Requirements (Non-Kiro Mode)**: Collect and organize requirements from standard markdown files
- [ ] **Aggregate Architecture (Non-Kiro Mode)**: Generate architecture documentation from existing markdown files
## Contributing
This is an open source project. Contributions welcome!
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Directory structure
```
.
├── cli_tools/ # cli commands and subcommands
├── config/ # configuration related code (more useful for future features)
├── organize # Code related to the organize subcommand
├── requirements # Code related to the requirements subcommand
│── templates # Semantic doc matching template (used in `organize`)
│── tests_and_validations # test scripts written by Claude
```
## Notes
### Why did I build this
I've been working on [gjalla](https://gjalla.io) which helps give teams an system-level view into how their software works and how it has changed over time... the key pain point here is that docs aren't always reconciled with the actual implementation. One of the challenges is has been doc sprawl and acclerating rate of change to codebases as teams start to adopt agentic coding tools. After testing out Kiro, I really liked the concept of spec-driven development, and liked that kiro seemed to be the first attempt at standardizing some of these specs. I wanted to build a couple of tools to help with actual pain points I have when working with agentic tools, including doc sprawl (this tool will at least put the AI-generated docs into categories) and a lack of aggregate info. More coming soon, and I'd love your feedback and contributions!
Raw data
{
"_id": null,
"home_page": "https://github.com/elliemdaw/gjalla-cli",
"name": "gjalla",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "documentation markdown validation standardization cli ai",
"author": "Ellie",
"author_email": "ellie@gjalla.io",
"download_url": "https://files.pythonhosted.org/packages/a2/07/99007f4c430514a9068ba9a7081f555122c9a2665386c1987f5624c41941/gjalla-0.1.1.tar.gz",
"platform": null,
"description": "# gjalla CLI\n\nA CLI for organizing, aggregating, and standardizing requirements and architecture information from markdowns written by agentic coding tools.\n\n## Installation\n\n```bash\n# Install from PyPI\npip install gjalla\n\n# Install from source\npip install git+https://github.com/elliemdaw/gjalla-cli.git\n```\n\n## \ud83d\ude80 Quick Start\n\n### Organize Documentation\n\n```bash\n# Preview what would be organized\ngjalla organize <path to project> --dry-run\n\n# Apply the organization\ngjalla organize <path to project>\n\n# Undo if needed\n# NOTE: undo has only been tested for the most recent action\ngjalla undo <path to project>\n```\n\n### Aggregate Requirements\n\n```bash\n# Parse structured .kiro requirements\ngjalla requirements <path to project> --kiro\n\n# List existing requirements\ngjalla requirements <path to project> --list\n```\n\n## How It Works\n\n### Organization Process\n\n1. **\ud83d\udccb Document Discovery**: Finds all markdown files. Exclude patterns can be defined in .gjallaignore, otherwise falls back to common ignore patterns\n2. **\ud83c\udff7\ufe0f File Classification**: Uses regex patterns and lightweight NLP (`spacy`) to classify markdown files by type\n3. **\ud83d\udd27 Directory Creation**: Creates missing directories as needed (`specs/`, `specs/features/`, `specs/fixes/`, `specs/references/`... see below!)\n4. **\ud83d\udce6 File Movement**: Moves files to appropriate locations with conflict resolution\n5. **\ud83d\udcbe Backup**: Saves backup info for undo functionality\n\n### Directory Structure After Organization\n\n```\nmy-project/\n\u251c\u2500\u2500 aimarkdowns/\n\u2502 \u251c\u2500\u2500 features/ # User stories, feature specs\n\u2502 \u251c\u2500\u2500 fixes/ # Bug reports, fixes\n\u2502 \u251c\u2500\u2500 reference/ # Documentation, guides\n\u2502 \u251c\u2500\u2500 requirements_001.md # Generated requirements summary\n| \u251c\u2500\u2500 CLAUDE.md # if found and not excluded, it will be put here\n| \u2514\u2500\u2500 GEMINI.md # if found and not excluded, it will be put here\n\u251c\u2500\u2500 .gjalla/\n\u2502 \u251c\u2500\u2500 backups/ # Backup files for undo\n\u251c\u2500\u2500 .gjallaignore # for defining exclusion patterns\n```\n\n## Requirements\n\n### Kiro\n\ngjalla supports the structure of docs written by Kiro, found in `.kiro` directories:\n\n```\n.kiro/\n\u251c\u2500\u2500 specs/\n\u2502 \u251c\u2500\u2500 feature-name/\n\u2502 \u2502 \u251c\u2500\u2500 requirements_001.md # Kiro requirements\n\u2502 \u2502 \u251c\u2500\u2500 design.md # Kiro design\n\u2502 \u2502 \u2514\u2500\u2500 tasks.md # Kiro tasks\n\u2502 \u2514\u2500\u2500 another-feature/\n\u2502 \u2514\u2500\u2500 requirements_001.md\n```\n\n### Non-Kiro\n\n_Working on this!_\n\n## \ud83d\udea7 Coming Next\n\n- [x] **Update Requirements Status**: Mark requirements as implemented/partial/not-implemented\n- [ ] **Aggregate Architecture Spec (Kiro Mode)**: Generate comprehensive architecture documentation from .kiro structure\n- [ ] **Aggregate Requirements (Non-Kiro Mode)**: Collect and organize requirements from standard markdown files\n- [ ] **Aggregate Architecture (Non-Kiro Mode)**: Generate architecture documentation from existing markdown files\n\n## Contributing\n\nThis is an open source project. Contributions welcome!\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Directory structure\n\n```\n.\n\u251c\u2500\u2500 cli_tools/ # cli commands and subcommands\n\u251c\u2500\u2500 config/ # configuration related code (more useful for future features)\n\u251c\u2500\u2500 organize # Code related to the organize subcommand\n\u251c\u2500\u2500 requirements # Code related to the requirements subcommand\n\u2502\u2500\u2500 templates # Semantic doc matching template (used in `organize`)\n\u2502\u2500\u2500 tests_and_validations # test scripts written by Claude\n```\n\n## Notes\n\n### Why did I build this\n\nI've been working on [gjalla](https://gjalla.io) which helps give teams an system-level view into how their software works and how it has changed over time... the key pain point here is that docs aren't always reconciled with the actual implementation. One of the challenges is has been doc sprawl and acclerating rate of change to codebases as teams start to adopt agentic coding tools. After testing out Kiro, I really liked the concept of spec-driven development, and liked that kiro seemed to be the first attempt at standardizing some of these specs. I wanted to build a couple of tools to help with actual pain points I have when working with agentic tools, including doc sprawl (this tool will at least put the AI-generated docs into categories) and a lack of aggregate info. More coming soon, and I'd love your feedback and contributions!\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI tool for organizing, aggregating, and standardizing requirements and architecture information from markdowns written by agentic coding tools.",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/elliemdaw/gjalla-cli/issues",
"Homepage": "https://github.com/elliemdaw/gjalla-cli",
"Source": "https://github.com/elliemdaw/gjalla-cli"
},
"split_keywords": [
"documentation",
"markdown",
"validation",
"standardization",
"cli",
"ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a1e2d0a03e889841cb94bb7858566ce3abc3a1bcc567b5f60744e7295fa8d59",
"md5": "c22671b3f19361cdf4868a4fb6a684ee",
"sha256": "ea73dfed0451cffe1966fd556bfabe15b0379117bbe6ac629df53b96b3486b0c"
},
"downloads": -1,
"filename": "gjalla-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c22671b3f19361cdf4868a4fb6a684ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 84824,
"upload_time": "2025-08-03T03:22:15",
"upload_time_iso_8601": "2025-08-03T03:22:15.159755Z",
"url": "https://files.pythonhosted.org/packages/2a/1e/2d0a03e889841cb94bb7858566ce3abc3a1bcc567b5f60744e7295fa8d59/gjalla-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a20799007f4c430514a9068ba9a7081f555122c9a2665386c1987f5624c41941",
"md5": "3ca5b556ae72dbba9f4ebfa9d768ceaa",
"sha256": "c2ace8a37098be87405070e74842c563b9bdc0c10e818ceb2341fc95b60afda9"
},
"downloads": -1,
"filename": "gjalla-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3ca5b556ae72dbba9f4ebfa9d768ceaa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 76182,
"upload_time": "2025-08-03T03:22:16",
"upload_time_iso_8601": "2025-08-03T03:22:16.630930Z",
"url": "https://files.pythonhosted.org/packages/a2/07/99007f4c430514a9068ba9a7081f555122c9a2665386c1987f5624c41941/gjalla-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 03:22:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "elliemdaw",
"github_project": "gjalla-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "cryptography",
"specs": [
[
">=",
"3.4.8"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.1"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"1.8.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "spacy",
"specs": [
[
">=",
"3.4.0"
]
]
}
],
"lcname": "gjalla"
}
JSON
