Metadata-Version: 2.2
Name: bisos.startAiActivity
Version: 0.12
Summary: bisos.startAiActivity: Install AI Collaborative Development Templates
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.common
Requires-Dist: bisos.pyDblock
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

=====================================================================
bisos.startAiActivity: Install AI Collaborative Development Templates
=====================================================================

.. contents::
   :depth: 3
..

The Concept and Model of an AI Activity
=======================================

An **AI Activity** is a durable, collaborative effort between a human
and an AI assistant (Claude Code) toward a specific purpose — writing a
document, building new software, enhancing existing software, and so on.
Unlike a one-shot chat, an activity is expected to span many sessions,
possibly across machines and over long stretches of time. Its state,
conventions, and progress live in files under version control rather
than in any one session's memory.

Two org-mode files encode the activity, playing distinct roles:

-  ``AI-Activity.org`` describes the human's **usual way of doing that
   kind of work** — their conventions, preferred libraries, patterns,
   and gotchas. It is **reusable**: symlinked from a shared activity
   template so the same conventions apply to every project of that kind.
   Examples of concrete activities: ``bisos-pip`` (Python package
   authorship), ``xu-single`` (single-XU PyCS scripts), ``blee-panels``
   (Blee panel authorship), ``lcnt`` (LaTeX content).
-  ``AI-WorkPlan.org`` describes **this specific effort** — what will be
   built or written, broken into stages with TODOs. It is per-effort:
   edited freely, org-archived as work completes, and paired with
   ``AI-DevStatus.org`` which records where the effort stands right now.

Activities are classes of work; WorkPlans are instances. The templates
``/bisos.startAiActivity/`` installs are what encode this distinction on
disk — shared invariants and activity conventions are symlinked from a
templates repo (so improvements propagate); WorkPlan and DevStatus start
as safe-copies (so each effort owns its own state).

Collaboration Across People and Across Sessions
===============================================

An AI Activity is collaborative in two symmetric senses. It is
**human-to-human** — one person starts the activity, a colleague
continues it later, possibly on a different machine. And it is
**human-to-AI** — one Claude Code session begins the work, another
resumes it hours or weeks later with no memory of the earlier one. Both
are the same problem: **continuity across a discontinuity**. The state,
conventions, and open TODOs must live in files that a fresh reader —
human or AI — can pick up cold.

Overview
========

*bisos.startAiActivity* installs the ByStar AI collaborative development
template set — ``CLAUDE.md``, ``AI-WORKFLOW.org``, ``AI-Activity.org``,
``AI-DevStatus.org``, ``AI-WorkPlan.org``, plus a ``.claude/`` directory
with ``settings.json``, ``commands/``, and optionally ``skills/`` — into
a project directory, git repo root, or subproject.

This package is **just the execution engine** — the template content
lives in a separately-cloned repo
(https://github.com/bxexamples/aiActivityTemplates, or your own fork).
See `Two-Part
Architecture <#two-part-architecture-execution-engine--templates>`__
below for details.

The installed layout is **hierarchical and Claude-consumable**. Files
fall into two classes:

-  **Invariants**, symlinked from ``mother/`` (``CLAUDE.md``,
   ``AI-WORKFLOW.org``, ``.claude/settings.json``,
   ``.claude/commands/``). Because they are symlinks to a shared source,
   an edit to ``mother/`` propagates automatically to every project that
   has been ``initiate``-d against that templates base.
-  **Activity-specific** files, from ``<activity>/``
   (``AI-Activity.org`` symlinked; ``AI-DevStatus.org`` and
   ``AI-WorkPlan.org`` safe-copied and editable; optionally
   ``.claude/skills/`` symlinked from ``<activity>/_skills/`` for
   on-demand task-specific instructions).

Claude Code consumes this hierarchy automatically. On startup it walks
upward from the current working directory collecting every
``CLAUDE.md``, which in turn imports (imports ``AI-WORKFLOW.org`` +
``AI-Activity.org`` + ``AI-DevStatus.org`` + ``AI-WorkPlan.org`` via
``@`` directives). Nested subprojects installed with ``initiateSub`` use
a slim ``CLAUDE.md`` that imports only the local trio; the invariants
are inherited from an ancestor via the same walk-up, avoiding
duplication.

bisos.startAiActivity is a python package that uses the
`PyCS-Framework <https://github.com/bisos-pip/pycs>`__. It provides the
``startAiActivity.cs`` command with the following operations:
``userConfig_set/get`` (persistent config), ``initiate`` (base install),
``initiateSub`` (slim subproject overlay), ``aiSuspend`` / ``aiResume``
(reversible pause/restore), ``deClaudify`` (permanent removal), and
``examples`` (all invocations with the current templates base).

Details at github
=================

See https://github.com/bisos-pip/startAiActivity
