Metadata-Version: 2.4
Name: vibefree
Version: 0.2.0
Summary: A tiny CLI initializer for vibe coding projects that generates .memory and .harness scaffolding.
Author: lemonmindyes
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/lemonmindyes/vibefree
Project-URL: Repository, https://github.com/lemonmindyes/vibefree
Project-URL: Issues, https://github.com/lemonmindyes/vibefree/issues
Keywords: cli,agents,scaffolding,vibe-coding
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# vibefree 🚀

`vibefree` 是一个轻量级 vibe coding 项目初始化工具，用于生成 `.memory` 和 `.harness` 上下文结构。

它的目标是帮助开发者在使用 opencode / coding agent / AI coding workflow 时，快速建立项目记忆、开发规则、架构上下文和任务交接入口。

GitHub: <https://github.com/lemonmindyes/vibefree>

作者: `lemonmindyes`

## ✨ 功能特性

- 一键生成 `.memory`
- 一键生成 `.harness`
- 默认不覆盖已有文件
- 适合 opencode / coding agent 工作流
- 轻量、可读、可手动维护
- 支持当前目录初始化
- 支持创建新项目目录并初始化

## 📦 安装

从 PyPI 安装：

```bash
pip install vibefree
```

## ⚡ 使用

在当前目录初始化：

```bash
vibefree init
```

创建并初始化一个新项目目录：

```bash
vibefree init my-project
```

如果 `my-project` 不存在，`vibefree` 会创建它；如果已存在，则会在其中补齐缺失的上下文文件。

已有文件不会被覆盖，适合在项目演进过程中重复运行。

## 🧠 `.memory`

`.memory` 用于保存长期有效的项目上下文，让 coding agent 能够快速恢复项目状态。

- `README.md`: memory 入口说明、读取顺序和文件职责
- `rules.md`: memory 读取、更新和写作规则
- `context.md`: 当前项目目标、状态、常用命令、关注点和约束
- `decisions.md`: 长期技术决策、项目约定和需要避免的事项
- `sessions.md`: 最近会话交接记录
- `archive/`: 已归档但仍需保留的旧上下文

## 🧭 `.harness`

`.harness` 用于保存 coding agent 的协作入口、架构说明、工作流和质量规则。

- `AGENTS.md`: agent 开始工作时的推荐读取顺序
- `ARCHITECTURE.md`: 系统结构和架构决策记录
- `WORKFLOW.md`: 开发流程和 memory 使用方式
- `QUALITY.md`: 测试、质量和安全规则
- `plans/`: 可选的任务计划目录

## 🗂️ 生成结构

```text
.memory/
├── README.md
├── rules.md
├── context.md
├── decisions.md
├── sessions.md
└── archive/
    └── .gitkeep

.harness/
├── AGENTS.md
├── ARCHITECTURE.md
├── WORKFLOW.md
├── QUALITY.md
└── plans/
    ├── active/
    │   └── .gitkeep
    └── completed/
        └── .gitkeep
```

## 🛠️ 本地开发

创建虚拟环境：

```bash
python -m venv venv
```

安装本地开发版本：

```bash
pip install -e ".[dev]"
```

运行测试：

```bash
pytest
```

构建发布包：

```bash
python -m build
```

## ✅ CI

项目使用 GitHub Actions 运行 CI。

- Pull Request 会自动运行测试和构建检查。
- push 到 `main` 或 `master` 会自动运行测试和构建检查。
- CI 会执行：
  - `pip install -e .`
  - `pytest`
  - `python -m build`
  - `twine check dist/*`

## 🚢 Release

项目通过 GitHub Actions 和 PyPI Trusted Publishing 发布到正式 PyPI。

`0.2.0` 是一次 memory scaffolding redesign，重点更新生成的 `.memory` 结构，并保持项目轻量。

发布流程：

1. 确认 `pyproject.toml` 中的 `version` 已更新。
2. 确认测试通过。
3. 创建并推送 tag：

```bash
git tag v0.2.0
git push origin v0.2.0
```

推送匹配 `v*` 的 tag 后，GitHub Actions 会构建包并发布到正式 PyPI。

发布使用 PyPI Trusted Publishing / OIDC，不推荐在仓库或 GitHub Secrets 中保存 PyPI API Token。

## 🔒 安全提示

- 不要把 token、API key、password、secret 或私有凭据写入 `.memory` 或 `.harness`。
- 提交前检查上下文文件，避免包含本地绝对路径、私有账号或临时调试信息。
- `vibefree init` 默认不会覆盖已有文件，但仍建议在重要项目中配合 Git 使用。

## 📄 License

Apache License 2.0. See [LICENSE](LICENSE).
