Metadata-Version: 2.4
Name: vibefree
Version: 0.2.1
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`
- 默认不覆盖已有文件
- 支持 `--force` 重置受管 `.memory` 文件
- 适合 opencode / coding agent 工作流
- 轻量、可读、可手动维护
- 支持当前目录初始化
- 支持创建新项目目录并初始化

## 📦 安装

从 PyPI 安装：

```bash
pip install vibefree
```

## ⚡ 使用

在当前目录初始化：

```bash
vibefree init
```

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

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

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

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

如需重置受管 `.memory` 文件为默认模板：

```bash
vibefree init --force
```

重复运行 `init` 会清理 `.memory` 下非目标结构并补齐缺失文件；默认不覆盖已有的 `README.md`、`rules.md`、`meta.md`、`project.md`，使用 `--force` 时会覆盖这些受管 memory 文件。

## 🧠 `.memory`

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

- `README.md`: Agent 入口文件，说明读取顺序、文件职责和维护边界。
- `rules.md`: memory 维护规则，说明何时创建、更新、删除和替换内容。
- `meta.md`: 项目必要元信息，包括项目名称、用途、阶段、技术栈、常用命令、环境说明和约束。
- `project.md`: 项目重要信息，包括当前目标、关键设计、关键修改、当前状态、TODO、已知问题和决策。

`.memory` 只维护以上四个文件。旧信息过期时直接更新或删除，不归档；Agent 应优先更新已有内容，避免重复追加。

### Agent 使用流程

1. 初始化 memory：运行 `vibefree init`，生成 `.memory` 和 `.harness`。
2. 新 session 读取 memory：先读 `.memory/README.md`，再按顺序读 `.memory/rules.md`、`.memory/meta.md`、`.memory/project.md`。
3. 完成任务后更新 `project.md`：记录长期有价值的关键修改、当前状态、TODO、已知问题或决策。
4. 项目信息变化后更新 `meta.md`：维护项目用途、阶段、技术栈、常用命令、环境说明和约束。

不要创建旧结构文件或目录；不再使用 `archive`、`logs`、`context.md`、`decisions.md`、`sessions.md`。

## 🧭 `.harness`

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

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

## 🗂️ 生成结构

```text
.memory/
├── README.md
├── rules.md
├── meta.md
└── project.md

.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。

当前 memory scaffolding 统一为四文件结构：`README.md`、`rules.md`、`meta.md`、`project.md`，并保持项目轻量。

发布流程：

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).
